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v  ABSTRACT 

The  PP  system  provides  an  efficient  implementation  of  the  Common  Lisp  pretty  printing 
function  PPRINT.  In  addition,  PP  goes  beyond  ordinary  pretty  printers  by  providing 
mechanisms  which  allow  the  user  to  control  the  exact  form  of  pretty  printed  output.  This  is 
done  by  extending  Lisp  in  two  ways.  First,  several  new  FORMAT  directives  are  provided  which 
support  dynamic  decisions  about  the  placement  of  newlines  based  on  the  line  width  available 
for  output.  Second,  die  concept  of  print-self  methods  is  extended  so  that  it  can  be  applied  to 
lists  as  well  as  to  objects  which  can  receive  messages.  Together,  these  extensions  support  pretty 
printing  of  both  programs  and  data  structures. 

The  PP  system  also  modifies  the  way  that  the  Lisp  printer  handles  the  abbreviation  of 
output.  The  traditional  mechanisms  for  abbreviating  lists  based  on  nesting  depth  and  length 
are  extended  so  that  they  automatically  apply  to  every  kind  of  structure  without  the  user  having 
to  rake  any  explicit  action  when  writing  print-self  methods.  A  new  abbreviation  mechanism  is 
introduced  which  can  be  used  to  limit  the  total  number  of  lines  printed. 
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I  -  Introduction 

The  main  purpose  of  this  paper  is  to  serve  as  a  manual  for  the  Lisp  Machine  implcmentat  on  of  the  PP 
system  (which  can  be  used  by  loading  the  file  "PP"  from  the  LMLIB  directory).  PP  has  been  written  to  run 
under  releases  4  and  5  of  the  Symbolics  Lisp  Machine  system  [4]  and  the  documentation  in  this  paper  is 
directed  toward  these  releases.  PP  will  be  converted  to  run  in  other  releases  of  the  Lisp  Machine  system  as 
they  appear.  'Phis  conversion  will  lead  to  some  minor  changes  (as  indicated  below)  in  the  user  m.erfacc  due  to 
the  introduction  of  Common  Lisp  compatibility  into  Lisp  Machine  Lisp.  In  particular,  several  output  control 
variables  have  different  names  in  Common  Lisp. 

The  relevance  of  the  PP  system  is  not  restricted  solely  to  Lisp  Machine  Lisp.  The  system  has  been 
designed  ta  be  upward  compatible  with  Common  Lisp  and  could  be  implemented  with  little  modification  in 
most  Lisp  dialects.  Going  beyond  this,  many  of  the  ideas  discussed  in  this  paper  have  a  much  wider  area  of 
applicability.  For  example,  die  mechanisms  for  allowing  the  user  to  exercise  control  over  the  dynamic 
arrangement  of  output  could  be  incorporated  into  almost  any  programming  language  (e.g.,  into  the  formatted 
output  sta  ements  of  Fortran  or  PL  I). 

The  PF  system  provides  three  sets  of  features.  First,  as  described  in  Section  II,  PP  supports  several  of  the 
Common  Lisp  output  functions  and  output  control  variables.  In  particular,  it  provides  an  efficient 
implemen;ation  of  the  pretty  printing  function  PPRINT.  Second,  PP  goes  beyond  typical  pretty  printing 
systems  by  providing  a  flexible  interface  which  gives  the  user  detailed  control  over  how  program  structures 
and  data  structures  are  to  be  pretty  printed.  This  is  done  by  extending  the  standard  Lisp  concepts  of  FORMAT 
control  strings  (sec  Section  III),  and  print-self  methods  (see  Section  IV).  Third,  as  described  in  Section  V,  the 
way  the  abbreviation  of  output  is  handled  by  Lisp  is  modified  and  extended. 

The  PP  system  is  based  on  the  earlier  GPRINT  system  [5,6].  The  main  difference  between  the  two  systems 
is  that  PP  !ias  a  greatly  improved  user  interface.  People  who  have  used  GPRINT  will  recognize  that  most  of  the 
features  of  PP  descend  from  features  of  GPRINT,  however  this  paper  assumes  no  knowledge  of  GPRINT. 

The  pretty  printing  algorithm  used  by  PP  is  essentially  the  same  as  the  one  used  by  GPRINT,  though  it  has 
been  streamlined  and  made  considerably  more  efficient.  This  paper  docs  not  go  into  a  detailed  discussion  of 
the  algorithm  since  it  is  fully  discussed  elsewhere  (sec  [2,5]).  However,  it  should  be  noted  that  a  key  aspect  of 
the  algorithm  is  that  it  is  an  inherently  fast  linear  algorithm  which  uses  very  little  storage.  As  a  result,  pretty 
printing  is  not  significantly  slower  than  ordinary  printing. 
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11  -  Basic  Output  Functions  and  Control  Variables 

The  PP  system  supports  several  of  the  Common  Lisp  output  functions  and  control  variables  which  arc  not 
supported  by  release  5  of  Lisp  Machine  Lisp.  These  functions  and  variables  arc  discussed  in  detail  in  the 
Common  Lisp  documentation  [3]  and  summarized  below. 

Pretty  Printing 

The  variable  *PRINT-PRETTY*  (which  has  a  default  value  of  NIL)  controls  pretty  printing.  When  this 
variable  is  non-NlL  it  causes  all  of  the  standard  output  functions  (PRIN1,  PRINC,  etc.)  to  perform  pretty 
printing.  The  function  PPRINT  binds  *PRINT-PRETTY*  to  T  while  printing  its  argument  and  therefore  forces 
pretty  printing. 

PPRINT  object  &opt1onal  stream 

This  is  the  same  as  the  function  PRINT  except  that  it  binds  *PRINT-PRETTY*  to  T,  does  not  print  a  trailing 
space,  and  returns  no  values. 


Abbreviation 

The  PP  system  supports  length  and  depth  abbreviation  under  control  of  the  variables  PRINLENGTH  and 
PRINLEVEL.  (When  Common  Lisp  compatibility  is  introduced  these  variables  will  be  called 
•  PRINT-LENGTH*  and  *PRINT-LEVEL*).  This  abbreviation  is  supported  both  when  pretty  printing  and  when 
not  pretty  printing.  As  discussed  in  Section  V,  the  way  in  which  this  abbreviation  is  handled  is  modified  in 
order  to  make  it  more  convenient  to  use.  In  addition,  a  new  kind  of  abbreviation  is  supported  which  can  be 
used  to  limit  the  total  number  of  lines  printed.  As  discussed  in  Section  V,  this  abbreviation  is  controlled  by 
the  variable  PP:  *PRINT-LINES*. 


The  Printing  of  Escape  Characters 

The  variable  «PR INT-ESCAPE*  (which  has  a  default  value  of  T)  controls  the  printing  of  escape  characters. 
The  function  PRINC  binds  *PRINT-ESCAPE*  to  NIL.  Other  output  functions  (e.g.,  PRINT  and  PPRINT)  bind 
•  PRINT-ESCAPE*  to  T. 


A  Neutral  Output  Function 

The  most  basic  Common  Lisp  output  function  is  the  function  WRITE.  Unlike  the  other  output  functions, 
WRITE  is  neutral  in  that  it  docs  not  force  the  specification  of  values  for  any  of  the  output  control  variables. 
The  function  WRITE  docs,  however  take  keyword  arguments  which,  if  supplied,  specify  values  for  output 
control  variables.  The  implementation  of  WRITE  provided  by  PP  supports  a  new  keyword  :  LINES  which 
corresponds  to  the  variable  PP:*PRINT-LINES*. 

WRITE  object  &key  :stream  :escape  :base  :pretty  :level  : length  : 1 1  nes  :array 
:rad1x  : c i rc  1  e  :casa  :gensym 

This  function  is  like  PRIN1  except  that  it  does  not  force  *PRINT-ESCAP£*  to  be  T.  The  .‘STREAM  keyword 
argument  (which  defaults  to  STANDARD-OUTPUT)  specifies  the  output  stream.  The  other  keyword 
arguments  allow  the  specification  of  values  for  the  control  variables  ‘PRINT- ESCAPE*.  BASE, 
•  PRINT-PRETTY*,  PRINLEVEL.  PRINLENGTH,  PP : ‘PRINT-LINES*,  SI : *PRINARRAY*,  ‘PRINT-RADIX*, 
♦PRINT-CIRCLE*.  *PRINT-CASE*,  and  *PRINT-GENSYM*  respectively.  (Ihe  last  four  of  these  variables 
arc  not  supported  by  release  5  of  the  Lisp  Machine  System.) 
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A  Neutral  Format  Directive 

PP  provider  a  new  FORMAT  directive  ~W  which  corresponds  to  calling  the  function  WRITE  without  any 
keyword  erguments  --  i.e.,  in  contrast  to  ~A  and  ~S  it  is  neutral  in  that  it  obeys  the  value  of  »PR  INT-ESCAPE* 
rather  than  specifying  its  value.  The  directive  ~W  takes  the  same  parameters  as  ~A  ard  ~S  --  i.e., 
-mincol ,colinc .  minpad ,  padcharW.  As  with  -A  and  ~S  the  atsign  flag  causes  spacing  to  be  inserted  on  the  left 
rather  than  on  the  right. 

The  colon  flag  has  a  different  meaning  from  the  one  used  for  ~A  and  ~S.  If  the  colon  flag  is  used  with  ~W 
then  seveial  of  the  output  control  variables  are  given  values  which  are  useful  when  pretty  printing  is  desired. 
Using  die  colon  flag  binds  *PRINT-PR£TTY*  anc  *PRINT-ESCAPE*  to  T  forcing  pretty  printing  and  the 
printing  of  escape  characters  and  binds  PRINLEVEL,  PRINLENGTH,  and  PP :  *PRINT-LINES*  to  NIL  turning  off 
abbreviation.  The  use  of -W  with  and  without  the  colon  flag  is  illustrated  in  the  following  example. 

(LEI  ( ( *PRINT-PRETTY*  NIL) 

(•PRINT-ESCAPE*  NIL) 

(PRINLENGTH  2) 

(X  '(QUOTE  ("a"  "b"  "C")))) 

(FORMAT  T  "~W  ~:W"  X  X)) 

The  output  produced  by  the  example  is  shown  below.  Since  *PRINT-PRETTY*  and  *PRINT-ESCAPE»  are 
bound  to  MIL,  and  PRINLENGTH  is  bound  to  2,  the  first  use  of  ~W  produces  output  which  is  not  pretty  printed 
and  which  is  printed  without  escape  characters,  and  which  is  abbreviated  as  shown.  The  use  of  ~:W  forces 
pretty  printing  and  die  printing  of  escape  characters,  and  suppresses  the  abbreviation. 

(QUOTE  (a  b  ...))  '("a”  "b"  "c") 

If  the  LET  bound  *PRINT-PRETTY*  and  ‘PRINT-ESCAPE*  to  T,  and  PRINLENGTH  to  NIL,  then  both 
outputs  would  be  the  same. 

A  More  Efficient  Implementation  of  Format 

As  will  become  clear  in  the  next  section,  the  user  interface  to  the  pretty  printing  facilities  provided  by  the 
PP  system  centers  around  the  function  FORMAT.  This  leads  to  a  very  convenient  interface  which  builds  on  top 
of  die  standard  FORMAT  directives.  Unfortunately,  the  function  FORMAT  is  rather  inefficient  due  to  the  fact 
that  the  control  string  is  executed  intcrprctivcly.  In  order  to  combat  this  problem,  a  macro  is  provided  which 
creates  efficient  compiled  code  corresponding  to  a  FORMAT  control  string. 

PP: FAST- FORMAT  destination  control-string  &rest  args 

This  macro  is  the  same  as  the  function  FORMAT  except  diat  destination  is  required  to  cither  be  a  literal  NIL 
or  a  literal  T  or  a  stream  --  it  cannot  be  a  string.  PP:  FAST-FORMAT  is  advantageous  to  use  because,  if  the 
control-string  is  a  sufficiently  simple  constant,  the  output  will  be  performed  significantly  faster  than  it 
woulc  be  by  FORMAT. 

At  the  current  time,  PP:  FAST-FORMAT  is  only  capable  of  compiling  relatively  simple  FORMAT  control 
strings  su<  h  as  the  ones  used  as  examples  in  diis  paper.  However,  there  is  no  reason  why  it  could  not  be 
extended  .o  diat  it  could  compile  almost  all  possible  FORMAT  control  strings. 

In  order  to  support  rapid  pretty  printing  of  programs,  PP  internally  uses  die  function  PP:  FAST-FORMAT 
instead  of  FORMAT  wherever  possible.  T  his  approximately  triples  the  speed  of  the  system. 
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Interactive  Output  Control  Variables 

In  keeping  with  traditional  Lisp  practice,  the  style  of  output  (e.g.,  whether  escape  characters  should  be 
printed  and  whether  abbreviation  should  be  used)  is  controlled  by  dynamic  variables.  One  effect  of  this 
design  decision  is  that  if  these  variables  are  given  particular  top  level  values,  these  values  become  the  default 
values  for  all  output.  Unfortunately,  this  is  not  always  desirable.  For  example,  one  might  well  want  to  use 
abbreviation  when  printing  the  interactive  output  from  the  READ-EVAL-PRINT  loop  and  yet  not  want  to  use 
abbreviation  for  lower  level  output  inside  programs  (e.g.,  when  writing  to  files,  or  strings).  In  this  situation, 
one  is  forced  to  turn  abbreviation  on  globally  and  then  explicitly  turn  it  off  for  each  lower  level  call  on  an 
output  function. 

The  PP  system  combats  this  problem  by  providing  a  mechanism  for  specifying  a  set  of  values  for  the 
output  control  variables  which  apply  only  to  interactive  output  and  not  to  other  output.  This  mechanism  is 
based  on  the  special  Lisp  Machine  variable  PRINl  (inherited  from  MacLisp)  which  specifies  a  printing 
function  which  the  Lisp  system  will  use  for  much  of  its  interactive  output  to  the  user.  For  example,  the  Lisp 
READ-EVAL-PRINT  loop  uses  the  value  of  PRIN1  to  display  results  to  the  user.  (It  should  be  noted  that,  as  of 
release  5  of  the  Lisp  Machine  system,  setting  the  value  of  the  variable  PRIN1  unfortunately  does  not  succeed 
in  controlling  all  of  the  interactive  output  to  the  user.  For  example,  the  debugger  does  not  use  the  value  of 
PR  INI  when  displaying  the  contents  of  program  variables  in  a  stack  frame.) 

A  function  PP:  interactive -WRITE  is  provided  which  is  intended  to  be  used  as  the  value  of  the  variable 
PRINl.  A  second  function  PP:SET-INTERACTIVE-CONTROL-VARIABLES  is  provided  which  controls  the 
printing  initiated  by  PP :  INTERACTIVE-WRITE. 

PP: INTERACTIVE-WRITE  object  &opt1onal  Stream 

This  function  is  similar  to  the  standard  Common  Lisp  function  WRITE  except  that  it  is  sensitive  to  the 
control  values  specified  by  PP : SET- INTERACTIVE- CONTROL- VARIABLES  rather  than  to  the  standard 
output  control  variables. 

PP:SET-INTERACTIVE-CONTROL-VARIABLE$  &key  :escape  :base  :pretty  : level  : length  : lines 

:array  :radix  :c1rcle  :case  :gensym 

This  function  specifics  the  output  control  variable  values  to  be  used  by  the  function 
PP:  interactive-write.  The  keyword  arguments  correspond  to  the  control  variables 
•PRINT-ESCAPE*,  BASE,  *PRINT-PRETTY»,  PRINLEVEL,  PRINLENGTH,  SI : *PRINARRAY*. 

•  PRINT-RADIX*,  *PRINT-CIRCLE*,  »PRINT-CASE*,  and  »PRINT-GENSYM*  respectively.  (The  last  four 
of  these  variables  are  not  supported  by  release  5  of  the  Lisp  Machine  System.) 

The  recommended  way  to  utilize  this  mechanism  is  to  use  the  function  PP:  INTERACTIVE-WRITE  as  the 
value  of  the  variable  PRINl  and  set  up  interactive  control  variable  values  as  shown  below.  Experience  has 
shown  die  values  illustrated  (which  are  the  default)  to  be  particularly  useful. 

(SETQ  PRINl  rPP:  INTERACTIVE -WRITE) 

( PP : SET -INTERACTIVE -CONTROL -VARIABLES  ’:ESCAPE  T 

' : PRETTY  T 
’ : LEVEL  NIL 
'.•LENGTH  NIL 
' : LINES  4) 
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III  -  Controlling  the  Arrangement  of  Output 

By  extending  the  concept  of  a  FORMAT  control  string,  the  PP  system  makes  it  possible  to  give  explicit 
directions  for  how  something  is  to  be  pretty  printed.  The  discussion  below  assumes  that  the  reader  has  a  basic 
understanding  of  the  function  FORMAT.  The  Lisp  Machine  documentation  [4]  describes  FORMAT  in  detail. 

Two  basic  concepts  underlie  the  way  PP  supports  the  dynamic  arrangement  of  output  -•  logical  blocks  and 
conditional  newlines.  The  output  as  a  whole  is  divided  up  hierarchically  into  logical  blocks  and  sub-blocks. 
Each  logical  block  is  divided  up  into  sections  by  positions  where  conditional  newlines  are  specified.  When 
printing  tfe  output,  each  logical  block  is  printed  on  a  single  line  if  possible.  If  a  logical  block  is  too  long  to  be 
printed  on  a  single  line  and  *PRINT-PRETTY*  is  T  then  newline  characters  are  inserted  at  appropriate 
condition;  1  newline  positions  in  the  block  in  order  to  print  the  block  on  several  lines.  The  pretty  printing 
algorithm  uses  internal  buffering  of  the  output  so  that  it  can  determine  which  way  to  print  a  logical  block 
before  actually  outputting  any  of  the  characters  in  the  block. 

As  an  example  of  how  logical  blocks  and  logical  block  sections  can  be  used  to  control  the  arrangement  of 
output,  co  isidcr  the  following.  Suppose  that  a  user  wants  to  print  out  the  line  of  output  shown  below. 

Roads  ELM  MAIN  Towns  BOSTON  LOWELL 

Suppose  farther  that  if  there  is  not  enough  room  to  print  the  output  on  a  single  line  then  the  user  would  like 
to  have  the  output  printed  on  two  lines  as  follows. 

Roads  ELM  MAIN 

Towns  BOSTON  LOWELL 

The  user  could  achieve  this  goal  by  grouping  the  output  as  a  whole  into  a  logical  block,  and  using  a 
conditional  newline  to  divide  the  block  into  two  sections  "Roads  ELM  MAIN  ",  and 
"Towns  BOSTON  LOWELL".  The  sections  would  be  printed  together  on  one  line  if  there  was  room,  and  on 
separate  lines  if  there  was  not.  The  way  in  which  a  user  can  specify  logical  blocks  and  conditional  newlines  is 
described  in  the  next  two  subsections. 
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Specifying  Logical  Blocks 

The  FORMAT  directive  -I . . .-.  is  used  to  specify  a  logical  block.  In  addition  to  specifying  a  logical  block, 
the  directive  descends  into  the  corresponding  FORMAT  argument  (which  must  be  a  list)  in  the  same 

way  as  the  standard  directive  ~l{ . . .  -}  (iterate  [once]  over  list).  If  the  corresponding  format  argument  is  not 
a  list,  then  it  is  printed  using  ~W  and  the  ~I . . directive  is  skipped.  The  directive  ~A  (terminate  iteration) 
can  be  used  to  exit  from  a  ~  I . . .  ~ .  just  as  it  can  be  used  to  exit  from  a  ~l{ . . . -}.  The  ~  1 . . .  ~ .  directives  in 
the  example  below'  decompose  the  list  argument  and  specify  three  logical  blocks  --  the  output  as  a  whole,  the 
road  names,  and  the  town  names. 

(FORMAT  T  "-IRoads  ~!~S  ~S~.  Towns  -1-S 
’((ELM  MAIN)  (BOSTON  LOWELL))) 

Each  logical  block  is  printed  in  one  of  two  ways:  single-line  mode  or  multi-line  mode.  The  decision  of 
which  mode  to  use  is  made  based  on  the  value  of  *PRINT-PRETTY*,  on  how  many  characters  are  in  the  block, 
and  on  how  much  line  width  is  available  for  printing  the  block. 

The  column  position  where  a  logical  block  must  start  (and  therefore  the  line  width  available  for  printing  it) 
is  determined  by  the  preceding  output.  If  *PRINT- PRETTY*  is  T  and  the  line  width  available  is  less  than  the 
size  of  the  logical  block  then  the  block  is  printed  in  multi-line  mode.  Otherwise,  single-line  mode  is  used. 

In  single-line  mode,  all  of  the  characters  in  a  logical  block  are  printed  as  a  unit  on  the  end  of  the  current 
line.  The  call  on  FORMAT  above  will  produce  the  output  shown  below  when  the  logical  blocks  are  printed  in 
single-line  mode. 

Roads  ELM  MAIN  Towns  BOSTON  LOWELL 

If  a  logical  block  is  printed  in  multi-line  mode,  then  newlines  arc  inserted  in  the  block  at  positions 
specified  by  the  user.  (In  the  contrived  example  above,  no  such  potential  newline  positions  are  specified.  As 
a  result,  printing  the  blocks  in  multi-line  mode  would  not  cause  any  change  in  the  output.) 

The  colon  flag  can  be  used  with  ~l . . .-.  with  the  same  meaning  as  with  ~w  --  i.e.,  *PRINT-PRETTY*  and 
•  PRINT-ESCAPE*  are  bound  to  T  and  PRINLEVEL,  PRINLENGTH,  and  PP :  *PRINT-LINES*  are  bound  to  NIL 
during  the  processing  of  the  logical  block. 

If  the  atsign  flag  is  used  with  -I . . .~.  then  the  directive  operates  on  all  of  the  rest  of  the  arguments  in 
much  the  same  way  as  the  standard  directive  ~l@{. . .-}  (iterate  [once]  over  arguments.)  However,  unlike 
~10{. . ~@! . . always  uses  up  all  of  the  remaining  arguments.  The  following  example  is  identical  to 
the  one  above  except  that  it  uses  -01...... 

(FORMAT  T  "~0 1  Roads  -l-S  ~S~.  Towns  ~!~S  1 

’(ELM  MAIN)  ’(BOSTON  LOWELL)) 
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Multi-Line  Mode  Conditional  Newlines 

The  places  in  a  logical  block  where  newlines  can  be  inserted  when  the  block  is  printed  in  multi-line  mode 
arc  called  conditional  newline  positions.  The  most  basic  kind  of  conditional  newline  is  called  a  multi- line 
mode  conditional  newline.  When  a  logical  block  is  printed  in  multi-line  mode,  a  newline  is  inserted  at  every 
multi-line  mode  conditional  newline  which  is  immediately  contained  in  the  block.  In  order  to  specify  a 
multi-line  mode  conditional  newline,  you  use  the  FORMAT  directive  as  shown  in  the  example  below.  This 
example  is  the  same  as  the  one  in  the  last  subsection  except  that  each  of  the  three  logical  blocks  is  divided  into 
two  sectio  is  by  a  directive.  If  a  directive  is  encountered  outside  of  a  logical  block,  it  is  ignored. 

( FOFMAT  T  "~:0!Roads  ~!~S  -.Towns  -1-S  ~_~S~.~." 

'(ELM  MAIN)  '(BOSTON  LOWELL)) 

If  the  line  width  available  is  at  least  34,  the  top  level  logical  block,  and  hence  the  whole  output,  will  be 
printed  in  single-line  mode  as  shown  in  the  last  subsection.  If  the  line  width  available  is  only  30,  the  top  level 
logical  blcck  will  be  printed  in  multi-line  mode.  As  shown  below,  this  causes  the  insertion  of  a  newline  at  the 
multi-line  mode  conditional  newline  which  is  immediately  contained  in  this  block. 

Roacs  ELM  MAIN 
Towrs  BOSTON  LOWELL 

If  the  line  width  available  is  only  15,  the  second  logical  sub-block  will  also  be  printed  in  multi-line  mode  as 
shown  below.  An  important  aspect  of  multi-line  mode  printing  is  that  whenever  a  newline  is  inserted,  the 
next  line  is  indented  so  that  it  begins  in  the  same  column  as  the  first  character  in  the  block. 

Roads  ELM  MAIN 
Towns  BOSTON 
LOWELL 

If  the  line  width  is  less  than  15,  all  three  logical  blocks  will  be  printed  in  multi-line  mode. 

Roads  ELM 
MAIN 

Towns  BOSTON 
LOWELL 

Further  reductions  in  the  line  width  available  would  not  alter  the  form  of  the  output  because  the  user  has  not 
specified  any  more  places  where  newlines  can  be  inserted. 


j  1 7rrr*r* 
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Prefixes  and  Suffixes 

The  portion  of  a  FORMAT  control  string  enclosed  in  can  be  divided  up  into  three  segments  by 

as  follows  -  \  prefix- \  body- \  suffix-..  If  the  enclosed  portion  is  only  divided  into  two  segments  then  the 
suffix  defaults  to  the  null  string.  If  the  portion  consists  of  only  a  single  segment  (as  in  the  examples  above) 
then  both  the  prefix  and  the  suffix  default  to  the  null  string.  The  prefix  and  suffix  must  both  be  constant 
strings  i.c.,  they  cannot  contain  FORMAT  directives.  The  body  can  be  any  arbitrary  FORMAT  control  string. 

When  a  ~! prefix-  body- ;  suffix- .  directive  is  processed,  the  prefix  is  printed  out  as  the  initial  characters 
in  the  logical  block,  and  the  suffix  is  printed  out  as  the  final  characters  in  the  logical  block.  This  behavior  is 
the  same  as  if  the  characters  in  the  prefix  and  suffix  were  simply  used  as  the  initial  and  final  characters 
(respectively)  of  the  body  except  for  two  things.  First,  whenever  a  newline  is  inserted  in  a  logical  block,  the 
next  line  is  indented  so  that  it  begins  in  the  same  column  as  the  first  character  in  the  body  of  the  block  --  i.e., 
it  is  indented  past  the  prefix.  Second,  the  suffix  is  always  printed  out  even  if  the  processing  of  the  body  is  cut 
short  (e.g.,  by  ~A  or  by  length  abbreviation  (see  Section  V)).  The  use  of  a  prefix  and  suffix  are  illustrated  in 
the  example  below. 

(DEFUN  PRINT-ADDRESS  (ADDRESS) 

(FORMAT  T  !#<~;Address  -  ~_~S~A  ~_~S~;>~."  ADDRESS)) 

The  function  print-address  prints  a  list  representing  a  street  address.  If  the  expression 
(print- ADDRESS  '  (256  maple)  ))  is  evaluated  with  a  line  length  of  10  the  following  output  is  produced. 
Note  that  the  house  number  and  street  name  are  indented  so  that  they  line  up  after  the  prefix 

ifKAddress  - 
256 

MAPLE> 

If  the  expression  ( PR  INT- ADDRESS  '  (MAPLE ) ) )  is  evaluated  with  a  line  length  of  10  the  following  output 
is  produced.  N  jte  that,  the  suffix  is  printed,  even  though  the  absence  of  a  house  number  causes  the  ~A 
directive  to  term:  ’ate  processing  of  the  body  before  the  end  of  the  body  is  reached. 

#<Address  - 
MAPLE> 
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Special  Features  of  Prefixes  and  Suffixes 

The  ~ ! . . .  ~ .  directive  can  be  given  a  parameter  which  controls  the  default  values  of  the  prefix  and  suffix. 
If  the  parameter  is  0  (the  default  value)  then  the  prefix  and  suffix  both  default  to  the  null  string  as  shown  in 
the  examples  above.  If  the  parameter  is  1  then  the  prefix  defaults  to  "{"  and  the  suffix  defaults  to  The 
use  of  this  parameter  is  illustrated  in  the  example  below. 

(FORMAT  T  "~1 : I ~S  ~_~S~."  (ELM  MAIN)) 

Assuming  a  line  width  of  8  the  above  call  on  FORMAT  produces  the  following  output 

(ELM 

MAIN) 

If  the  a  .sign  flag  is  used  with  the  ~ ;  directive  that  marks  the  end  of  the  prefix  in  a  ~  I . . .  ~ .  directive  then 
the  prefix  s  printed  before  every  line  in  the  logical  block,  instead  of  just  before  the  first  line.  This  feature  is 
illustrated  n  the  example  below. 

(FERKOR  : 0 ! ; ~8 ; Bound  variable  ~S  is  not  a  symbol  in  ~_~S . ~ " 

2  '(LET  ((2  X-VALUE))  (+  X-VALUE  X-VALUE))) 

Ihecall  or  F  ERROR  produces  the  following  output  assuming  a  line  length  of  45. 

>>Er,-or:  ;Bound  variable  2  is  not  a  symbol  In 
.(LET  ((2  X-VALUE)) 

;  (+  X-VALUE  X-VALUE)). 

Whenever  per-line  prefixes  arc  printed,  the  prefixes  on  the  second  and  subsequent  lines  are  indented  so 
that  all  the  prefixes  line  up.  The  call  on  FERROR  also  illustrates  that  the  FORMAT  directives  provided  by  PP  can 
be  used  in  a  format  control  string  which  is  not  directly  used  as  an  argument  to  the  FORMAT  function. 

Nested  logical  blocks  can  each  specify  a  per-line  prefix  as  in  the  example  below.  All  appropriate  per-line 
prefixes  are  printed  on  each  line  at  the  appropriate  indentation  points. 

(FORMAT  T  : 0 ! ; ;  ;  ~0;The  error  message  will  have  the  following  form~_~ 

>>Error:  —0 ! : ~0 ; Bound  variable  ~S  is  not  a  symbol  in 
2  '(LET  ((2  X-VALUE))  (+  X-VALUE  X-VALUE))) 

The  call  on  format  produces  the  following  output  assuming  a  line  length  of  50. 

;;;  The  error  message  will  have  the  following  form 
;;;  >>Error:  ;Bound  variable  2  Is  not  a  symbol  in 
; ;  ;  ;(Ui  ((2  X-VALUE)) 

; ; ;  ;  (  +  X-VALUE  X-VALUE)). 
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If-Needed  Conditional  Newlines 

PP  supports  a  second  kind  of  conditional  newline  (called  an  if- needed  conditional  newline)  which  allows 
more  flexible  control  over  where  newlines  are  placed  when  a  logical  block  is  printed  in  multi-line  mode.  A 
newline  is  inserted  at  an  if-needed  conditional  newline  only  if  the  following  section  of  output  is  too  long  to  fit 
on  the  end  of  the  current  line.  Note  that  the  following  section  of  output  is  all  of  the  output  up  to  die  next  place 
immediately  contained  in  the  block  where  a  new  line  can  occur,  or  die  end  of  the  block,  whichever  comes  first. 
I'he  pretty  prinung  algoridim  uses  internal  buffering  of  the  output  in  order  to  determine  whether  or  not  to 
insert  a  new  line  at  an  if-needed  conditional  newline  position  before  actually  outputting  any  of  the  characters 
in  the  following  section  of  output.  In  order  to  specify  an  if-needed  conditional  newline,  you  use  die  FORMAT 
directive  ~ _  as  shown  in  the  example  below.  If  a  - :  _  directive  is  encountered  outside  of  a  logical  block,  it  is 
ignored. 

(FORMAT  T  "Roads  ~:1~8{~S~A  ’(ELM  MAIN  MAPLE  CENTER  RIVER  HIGH)) 

The  FORMAT  control  string  uses  the  standard  directives  ~0{...~)  (iterate  over  arguments)  and  ~A 
(terminate  iteration)  in  order  to  decompose  the  list  argument.  Bach  element  of  the  list  is  printed  with  ~S.  A 
space  and  an  if-needed  conditional  newline  is  placed  after  each  clement  except  die  last. 

If  die  line  width  available  is  at  least  38,  the  call  on  FORMAT  above  will  print  on  one  line.  If  die  line  width  is 
only  25.  multi-line  mode  will  be  used  as  shown  below.  Only  one  newline  is  inserted  because  die  if-needed 
conditional  newlines  in  the  block  are  processed  one  at  a  dme  and  only  when  looking  at  the  if-needed 
conditional  newline  after  the  third  road  name  is  it  determined  that  the  following  section  of  the  block 
(i.e.,  "CENTER  ")  cannot  fit  on  die  end  of  the  line. 

Roads  ELM  MAIN  MAPLE 

CENTER  RIVER  HIGH 

If  the  line  width  is  only  20,  newlines  will  be  inserted  at  the  if-needed  conditional  newlines  after  the  second 
and  fourth  road  names. 

Roads  ELM  MAIN 

MAPLE  CENTER 
RIVER  HIGH 

If  the  line  width  is  less  than  15,  newlines  w  ill  be  inserted  at  all  of  the  if-needed  conditional  newlines. 

Roads  ELM 
MAIN 
MAPLE 
CENTER 
RIVER 
HIGH 
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Generalized  Print-Self  Functions 

PP  supports  a  generalized  kind  of  print-self  function  which  makes  it  possible  to  specify  how  to  pretty  print 
objects  other  than  flavor  instances  and  lists  with  CARS  which  are  symbols. 

PP:DEFINE-GENERALIZED-PRINT-FUNCTION  name  {object  stream)  predicate  Sbody  forms 

This  macro  defines  a  generalized  print-self  function  named  name.  Generalized  print-self  functions  are 
called  with  the  arguments  shown.  The  predicate  is  used  to  determine  whether  the  generalized  print-self 
function  is  applicable  to  a  given  object.  When  the  function  is  applicable,  die  forms  are  evaluated  to  print 
object  on  stream. 

Unlike  list  print-self  functions,  defining  a  generalized  print-self  function  does  not  cause  the  pretty  printer 
to  use  it.  It  must  be  explicitly  enabled  before  it  will  be  used. 

PP:GENERALIZED-PRINT-FUNCTION-ENABLEO-P  name 

Determines  whether  the  named  generalized  print-self  function  is  enabled.  SETF  can  be  used  to  enable  or 
disable  a  given  generalized  print-self  function. 

PP: WITH -GENERALI ZED- PR I NT- FUNCTION  name  &body  forms 

This  macro  evaluates  the  forms  with  the  specified  generalized  print-self  function  enabled. 

Whenever  any  object  is  to  be  pretty  printed,  every  enabled  generalized  print-self  function  is  tested  to  see  if 
it  is  applicable.  If  one  is  applicable  then  it  is  used  to  pretty  print  the  object.  (Note  diat  when  a  user-defined 
FORMAT  directive  is  used  to  print  an  object,  then  the  standard  output  functions  are  not  called  and  therefore, 
dispatching  to  generalized  print-self  functions  docs  not  occur.)  If  more  than  one  generalized  print-self 
function  is  applicable,  then  the  most  recently  enabled  function  will  be  used.  It  is  important  to  note  that 
dispatching  to  generalized  print-self  functions  is  only  performed  during  pretty  printing. 

The  example  generalized  print-self  function  below  causes  nil  to  print  out  as  "( )". 

(PP: DEFINE -GENERAL  I  ZED- PRINT- FUNCTION  NIL-AS-EMPTY-LIST  (OBJ  STREAM) 

(NULL  OBJ) 

(PRINC  "()"  STREAM)) 

'Ihe  use  of  this  generalized  print-self  function  is  illustrated  below. 

( PPRINT  NIL) 

(PP: WITH-GENERALIZED-PRINT- FUNCTION  NIL-AS-EMPTY-LIST 
(PRINT  NIL) 

(PPRINT  NIL)) 

(SETF  (PP:GENERALIZEO-PRINT-FUNCTION-ENABLED-P  ’NIL-AS-EMPTY-LIST)  T) 

(PPRINT  NIL) 

The  above  forms  produce  the  following  output.  The  first  call  on  PPRINT  docs  not  trigger  the  generalized 
print-self  function  because  it  is  not  enabled.  The  call  on  PRINT  docs  not  trigger  it  because  pretty  printing  is 
not  enabled.  The  second  call  on  PPRINT  triggers  the  generalized  print-self  function  because  the  function  is 
locally  enabled.  Ihe  third  call  on  PPRINT  triggers  the  generalized  print-self  function  because  the  function  has 
been  globally  enabled. 

NIL 

NIL 

0 

0 
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Predefined  List  Print-Self  Functions 

In  order  to  support  traditional  Lisp  pretty  printing  style,  the  PP  system  provides  predefined  list  print-self 
functions  for  all  of  the  standard  Lisp  program  constructs.  One  example  of  these  is  the  print-self  function  for 
COND  shown  in  the  last  subsection.  Another  example  is  the  list  print-self  function  for  QUOTE  shown  below. 
The  user  cm  change  the  way  any  given  kind  of  list  is  printed  by  defining  a  new  list  print-self  function  for  it. 

(PP:DE FINE-LIST- PRINT- FUNCTION  QUOTE  (LIST  STREAM) 

(COND  ((AND  ( LISTP  (COR  LIST))  (NULL  (CDDR  LIST))) 

(PP  :  FAS'1  -FORMAT  STREAM  "■~W"  (CADR  LIST))) 

(T  ( PP : FAST-FORMAT  STREAM  "~1\FILL\"  LIST)))) 

The  outpt  t  below  illustrates  the  way  quoted  objects  are  printed. 

1 (CCND  ((NULL  X)  'NULL)) 

There  are  several  interesting  things  to  note  about  the  way  the  print-self  function  for  QUOTE  is  written. 
First,  all  cf  the  predefined  list  print-self  functions  use  PP:  FAST -FORMAT  in  the  interest  of  efficiency.  Second, 
the  print-t elf  function  checks  to  sec  that  the  LIST  is  well  formed  in  order  to  guarantee  that  it  will  be  printed 
in  such  a  way  that  it  can  be  read  back  in.  Third,  the  list  print-self  function  uses  the  full  power  of  the  pretty 
printer  to  print  die  quoted  list  itself  so  that  the  output  will  be  aesthetic  when  the  quoted  list  is  a  program 
construct  is  in  the  example. 

During  pretty  printing,  if  a  list  has  no  list  print-self  function  specified  for  it  then  the  list  is  printed  in  one  of 
diree  way ;.  If  die  CAR  of  the  list  is  die  name  of  a  defined  function  (i.e.,  is  FBOUNDP),  then  the  list  is  printed  as 
a  function  call.  In  order  to  do  this  the  variable  ZWEI ;  *LISP-INDENT-OFFSET-ALIST»  is  consulted  to 
determine  what  indentation  pattern  to  use.  As  a  result  of  this,  the  pretty  printer  automatically  knows  how  to 
indent  corrcctly  everything  diat  Zwci  knows  how  to  indent  correctly.  This  includes  understanding  macros 
that  are  defined  using  die  keyword  &B0DY.  If  a  list  is  a  literal  LAMBDA  combination  (i.e.,  if  the  CAR  of  the  list  is 
a  list  who;e  CAR  is  die  symbol  LAMBDA)  then  the  list  is  printed  using  -ALINEARV  In  all  other  cases,  die  list  is 
printed  ming  -AFILLV 

When  •PRINT-PRETTY*  is  NIL,  then  every  list  is  printed  in  the  traditional  way  with  each  sublist  grouped 
together  as  a  logical  block. 
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List  Print-Self  Functions 

Print-self  methods  cannot  be  defined  for  lists.  This  is  unfortunate  since  lists  are  used  to  represent  both 
programs  and  a  wide  variety  of  data  structures.  PP  supports  a  concept  (similar  to  print-self  methods)  for  lists 
which  makes  it  possible  to  specify  how  to  pretty  print  particular  program  constructs,  and  particular  kinds  of 
list  data  structures.  PP  looks  at  the  CAR  of  every  list  to  be  pretty  printed  and  determines  whether  a  special  list 
print-self  function  has  been  defined  for  lists  which  begin  with  this  CAR.  It  is  important  to  note  that 
dispatching  to  list  print-self  functions  is  only  performed  during  pretty  printing.  When  •PRINT-PRETTY*  is 
NIL  all  lists  are  printed  in  the  standard  way. 

PP:  DEFINE -LIST -PRINT- FUNCTION  symbol  (list  stream)  &body  forms 

This  macro  defines  a  list  print-self  function  for  lists  whose  CAR  is  symbol.  List  print-self  functions  are 

called  with  the  arguments  shown.  The  forms  are  evaluated  to  print  list  on  stream. 

When  a  list  print-self  function  is  defined  for  a  symbol  it  replaces  any  list  print-self  function  which  was 
previously  defined  for  that  symbol.  In  order  to  remove  a  previously  defined  list  print-self  function  without 
defining  a  new  one,  you  can  use  the  function  (PP  :UNDEFINE-LIST-PRINT-FUNCTION  symbol). 

As  an  example  of  using  PP:OEFINE-LIST-PRINT-FUNCTION  consider  the  following  definition  ofhow  to 
print  CONDs.  The  FORMAT  string  prints  the  first  element  of  the  list  followed  by  a  space.  It  then  sets  the 
indentation  at  the  character  position  corresponding  to  this  point  and  specifies  a  miser  mode  conditional 
newline.  It  then  uses  ~3{ . . .  -}  to  iterate  over  the  list  of  COND  clauses  using  the  directive  -ALINEARX  to  print 
each  clause. 

(PP:DEFINE-LIST- PRINT-FUNCTION  COND  (LIST  STREAM) 

(PP:  FAST-FORMAT  STREAM  I~8_*-(§{~I \LINEAR\~A  LIST)) 

The  above  list  print-self  function  causes  CONDs  to  be  printed  in  the  standard  style.  If  a  COND  cannot  be 
printed  on  a  single  line  then  each  clause  is  printed  on  a  separate  line.  If  a  clause  cannot  be  printed  on  a  single 
line,  then  each  clement  of  the  clause  is  printed  on  a  separate  line.  This  is  illustrated  in  the  output  below. 

(COND  ((TEST  X)  ( 00 -THIS  X)) 

(COND 

(SETQ  X  (CAR  X)) 

X)) 

A  basic  concept  behind  list  print-self  functions  is  that  the  type  of  a  list  can  be  determined  by  looking  at  its 
CAR.  This  is  true  much  of  the  time  when  looking  at  program  constructs  and  named  data  structures 
implemented  as  lists.  However,  it  is  not  true  all  the  time.  This  can  cause  the  pretty  printer  to  make  mistakes. 
Lor  example,  if  a  list  begins  with  the  symbol  CONO  then  it  will  in  general  always  be  printed  with  tire  list 
print-self  function  above  even  if  it  is  not  actually  a  COND  form  (e.g.,  even  if  it  is  just  an  arbitrary  piece  of  data 
such  a  list  of  function  names). 

An  important  aspect  of  the  user-defined  FORMAT  directives  is  that  they  can  be  used  to  prevent  the 
cironcotis  application  of  list  print-self  functions.  When  a  user-defined  FORMAT  directive  is  used  to  print  a  list, 
then  the  standard  output  functions  arc  not  called  and  therefore,  dispatching  to  list  print-self  functions  does 
not  occur.  I  he  print-self  function  for  COND  above  uses  the  directive -NLINEARN  to  print  each  COND  clause.  As 
a  result,  even  though  the  first  clement  of  the  second  clause  is  the  symbol  COND  the  second  clause  is  printed  in 
linear  style,  and  not  in  COND  style.  In  general,  user-defined  FORMAT  directives  should  be  used  instead  of  ~A, 
-S.  or  whenever  die  way  an  object  is  to  be  printed  is  controlled  by  the  context  of  its  use  rather  than  by  its 
intrinsic  properties. 
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IV  -  Print-Self  Functions 

A  key  feature  of  the  standard  output  functions  is  the  idea  of  print-self  methods  specifying  how  to  print 
flavor  instances  and  named  data  structures  implemented  as  arrays.  The  discussion  below  assumes  a  basic 
understanding  of  print-self  methods.  The  Lisp  Machine  documentation  [4]  describes  them  in  detail.  (Though 
Common  Lisp  does  not  have  print-self  methods  for  flavors,  it  does  support  the  concept  of  print-self  methods 
(called  :  P't  IN T- functions)  for  structures.) 

Dispatching  to  print-self  methods  is  supported  during  pretty  printing  in  exactly  the  same  way  as  it  is 
supported  during  ordinary  printing.  Consider  the  following  print-self  method  which  prints  out  the  instance 
variables  of  a  flavor  called  FAMILY. 

(DEI  FLAVOR  FAMILY  (MOTHER  CHILDREN)  () 

( : INITABLE-INSTANCE-VARIABLES  MOTHER  CHILDREN)) 

(DEf METHOD  < FAMILY  : PRINT-SELF )  (STREAM  &REST  IGNORE) 

( F  P : FAST- FORMAT  STREAM  "~0 l#<~ ; FAMILY  -  IMOTHER  ~W  -.CHILDREN  ~1\FILL\~;>~." 

MOTHER  CHILDREN)) 

(SET  Q  F  (MAKE-INSTANCE  'FAMILY 

-:M0THER  "Lucy" 

'•.CHILDREN  '("Mark"  "Barbara"  "Danny"  "Sally"))) 

Evaluating  (pprint  F )  when  the  line  width  is  45  produces  the  following  output.  In  the  course  of  pretty 
printing,  the  print-self  method  is  called  to  print  the  instance. 

#<FAMILY  -  MOTHER  "Lucy" 

CHILDREN  ("Mark"  "Barbara" 

"Danny"  "Sally")> 

Evaluating  (PRINT  F)  with  •PRINT-PRETTY*  bound  to  NIL  would  produce  the  output  below  no  matter 
how  little  line  width  were  available  for  printing  because  nothing  in  the  the  print-self  method  above,  or  in  the 
directive  -\F  I  LL\  forces  pretty  printing  to  occur.  An  important  aspect  of  the  PP  system  is  that  it  allows  you 
to  write  print-self  methods  which  specify  how  something  should  be  pretty  printed  without  forcing  pretty 
printing  to  occur. 

#< FAMILY  -  MOTHER  "Lucy”  CHILDREN  ("Mark"  "Barbara"  "Danny"  "Sally”)> 

Evaluating  ( PR  INC  F )  would  produce  the  following  output,  since  nothing  in  the  print-self  method,  or  in 
the  direct  vc~\ FILL\  forces  the  printing  of  escape  characters. 

#<FnMILY  -  MOTHER  Lucy  CHILDREN  (Mark  Barbara  Danny  Sally)> 
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Controlling  the  Margins 

In  order  to  work  properly,  the  pretty  printing  algorithm  used  by  PP  needs  to  know  the  line  length  available 
for  output.  In  general,  this  is  determined  by  querying  the  output  stream  when  the  outermost  logical  block  is 
entered.  However,  if  the  output  stream  does  not  support  the  :SIZE-IN-CHARACTERS  message  then  a  line 
width  of  95  is  assumed. 

The  variable  PP  •.•PRINT-RIGHT-MARGIN*  (which  has  a  default  value  of  NIL)  can  be  used  to  control  the 
right  margin  position.  If  this  variable  is  non-NIL  then  it  will  override  the  stream  and  be  used  as  the  line 
width. 

The  user  can  exercise  control  over  the  left  margin  by  simply  creating  a  logical  block  which  begins  at  thp 
desired  indentation.  The  pretty  printing  algorithm  will  then  continue  this  indentation. 

In  order  to  know  how  much  indentation  to  use  inside  of  a  logical  block,  the  pretty  printing  algorithm 
needs  to  know  the  column  position  where  the  logical  block  begins.  For  all  but  the  outermost  logical  block, 
the  column  position  of  the  start  of  a  block  is  determined  internally  by  the  pretty  printing  algorithm  relative  to 
the  starting  position  of  the  outermost  block.  In  order  to  determine  the  starting  position  of  the  outermost 
logical  block,  the  pretty  printing  algorithm  sends  the  output  stream  a  :READ-CURS0RP0S  message.  If  the 
output  stream  does  not  support  this  message,  then  the  pretty  printing  algorithm  assumes  that  the  outermost 
logical  block  begins  in  column  zero. 

As  an  example  of  the  above  points,  consider  the  following  function  which  pretty  prints  an  object  between 
two  specified  margins. 

(DEFUN  PPRINT- BE  TWEEN-MARGINS  (OBJECT  STREAM  LEFT  RIGHT) 

(LET  ( ( PP : *PR I  NT-RIGHT -MARGIN*  RIGHT)) 

(FORMAT  STREAM  "~%~0 1-VT-0 ! - : W~ .~  .  M  LEFT  OBJECT))) 

The  function  sets  the  right  margin  by  binding  the  variable  PP :  *  PRINT-RIGHT -MARGIN*.  It  then  sets  tire 
left  margin  by  going  to  a  new  line  (-%),  tabbing  over  to  the  column  specified  by  LEFT  (~VT),  and  starting  a 
logical  block.  The  object  to  be  printed  is  then  pretty  printed  inside  tire  block.  An  outermost  logical  block  is 
started  in  column  zero  in  order  to  insure  that  the  pretty  printing  algorithm  will  determine  the  correct  starting 
column  and  that  the  -VT  will  work  even  if  STREAM  does  not  support  tire  :READ-CURS0RP0S  message. 
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Special  Format  Directives  For  Lists 

PP  supplies  three  special  FORMAT  directives  for  printing  Lisp  lists.  The  first  of  these  is  called  ~\F  ilia  and 
prints  out  the  elements  of  a  list  with  as  many  elements  as  possible  on  each  line.  The  definition  of  this 
directive  is  shown  below.  In  analogy  with  ~! ~\FILL\  takes  a  numerical  parameter  (which  defaults 
to  0)  that  specifies  whether  parenthesis  should  be  printed  around  the  list  elements. 

( PP : DEFINE -FORMAT -DIRECTIVE  FORMAT : FILL  (LIST  STREAM  IGNORE  IGNORE 

&QPTI0NAL  (PARENS?  0)) 

(PP:FAST-FORMAT  STREAM  "~V!~@{~W~A  PARENS?  LIST)) 

The  standard  FORMAT  directives  ~0{ . . .-}  (iterate  over  arguments),  and  ~A  (terminate  iteration)  are  used 
in  order  to  iterate  over  the  list  argument.  A  ~w  is  used  to  print  each  element  of  the  list  A  space,  and  an 
if-needed  conditional  newline  are  printed  after  each  element  except  for  the  last  one.  The  use  of  -AFILLV  is 
illustrated  below. 

(FOFMAT  T  "~:01~1\FILL\~."  ’(ONE  TWO  THREE  FOUR  FIVE  SIX  .  SEVEN)) 

With  a  line  length  of  20  the  call  on  FORMAT  above  produces  the  following  output. 

(ONE  TWO  THREE  FOUR 
FIVE  SIX  .  SEVEN) 

Four  things  should  be  noticed  about  the  style  in  which  the  directive  ~\FILL\  is  written.  First,  it  does  not 
force  pretty  printing  to  occur.  It  simply  specifies  how  pretty  printing  should  be  carried  out  when 
•  print-pretty*  is  T.  Second,  ~w  is  used  to  print  out  the  elements  of  the  list  so  that  the  printing  of  escape 
characters  will  neither  be  forced  nor  prevented.  Third,  the  function  PP :  FAST-FORMAT  is  used  on  the  theory 
that  efficiency  is  important  since  -AFILLN  is  called  many  times  in  a  wide  variety  of  contexts.  Fourth,  due  to 
the  fact  that  ~A  checks  for  the  presence  of  a  non-NIL  atomic  CDR,  ~\FILL\  produces  reasonable  output  even 
when  it  is  given  a  malformed  list  as  its  argument 

The  second  special  FORMAT  directive  for  lists  is  called  -ALINEARV  and  prints  a  list  with  one  element  on 
each  line  when  the  list  cannot  be  printed  on  a  single  line.  The  third  is  called  ~\TABULAR\  and  prints  a  list  in  a 
tabular  form.  Both  of  these  directives  take  a  parameter  which,  if  specified  as  1,  causes  parentheses  to  be 
printed  around  the  list  elements.  The  directive  -ATABULARV  takes  a  second  a  parameter  (default  16)  which 
specifics  the  column  spacing  to  use.  These  two  directives  arc  demonstrated  in  the  call  on  FORMAT  below. 

(LET  ((X  '(ELM  MAIN  MAPLE  CENTER))) 

Format  t  "~:0i~i\linear\~x~,6\tabular\~."  x  x)) 

If  the  lint  length  is  30  then  this  will  produce  the  following  output 

(EL*  MAIN  MAPLE  CENTER) 

ELM  MAIN  MAPLE  CENTER 

If  the  lint  w  idth  is  15  then  this  will  produce  the  following  output 

(EL* 

MAIN 

MA’LE 

CENTER) 

ELM  MAIN 
MAP.E  CENTER 
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User-Defined  Format  Directives 

The  directives  ~A,  ~S,  and  ~W  all  call  the  standard  output  functions  in  order  to  print  the  corresponding 
FORMAT  argument.  The  standard  output  functions  decide  how  to  print  an  object  based  on  the  characteristics 
of  the  object.  Occasionally  it  is  important  to  be  able  to  bypass  this  decision  and  specify  a  non-standard  way  to 
print  something.  PP  provides  a  mechanism  for  allowing  the  user  to  define  new  FORMAT  directives  which 
specify  a  special  function  to  be  used  for  printing  the  corresponding  FORMAT  argument. 

PP:  DEFINE -FORMAT -DIRECTIVE  name  (arg  stream  colon  atsign  &rest  parameters)  &body  forms 

This  macro  defines  a  FORMAT  directive  which  prints  a  FORMAT  argument.  The  directive  can  be  used  ky 
putting  ~\package:name\  in  a  FORMAT  control  string.  (When  Common  Lisp  compatibility  is  introduce, 
such  directives  will  be  used  by  putting  -/package: name/  in  the  FORMAT  control  string.)  If  the  package 
prefix  is  omitted  it  defaults  to  the  package  FORMAT  rather  than  to  the  current  package. 

When  used,  a  user-defined  FORMAT  directive  is  called  with  the  arguments  shown.  The  first  argument 
arg  is  the  argument  to  FORMAT  which  is  to  be  printed  by  the  directive.  The  second  argument  stream  is  the 
stream  to  print  arg  on.  The  next  two  arguments  colon  and  atsign  are  non-NIL  if  and  only  if  the  colon 
and/or  atsign  flags  (respectively)  were  used  with  the  directive.  The  remaining  arguments  are  the 
parameters  specified  for  the  directive  in  the  FORMAT  control  string  (if  any).  The  forms  are  evaluated  to 
print  arg  on  stream. 

The  definition  of  a  format  directive  is  illustrated  below.  The  directive  takes  a  symbol  as  its  argument  and 
prints  it  out  followed  by  its  value. 

( PP : DEFINE -FORMAT-DIRECTIVE  SHOW-VALUE  (SYMBOL  STREAM  &REST  IGNORE) 

(FORMAT  STREAM  "~S  *  ~S”  SYMBOL  (SYMEVAL  SYMBOL))) 

(LET  ( ( ‘ROADS’  ’(ELM  MAIN))) 

(FORMAT  T  "-AUSER :SHOW-VALUE\"  ’*R0ADS*)) 

The  call  on  FORMAT  which  uses  the  user  defined  FORMAT  directive  SHOW-VALUE  produces  the  following 
output. 

•ROADS*  =  (ELM  MAIN) 

The  approach  presented  above  for  supporting  the  user  specification  of  a  printing  function  to  use  should  be 
contrasted  with  the  standard  FORMAT  directive  -Q.  This  directive  takes  an  argument  which  is  a  function  to  use 
to  print  a  second  argument.  The  problem  with  this  approach  is  that  it  requires  the  function  to  be  embedded 
in  the  argument  list.  If  the  FORMAT  directive  is  being  used  then  this  requires  that  the  function  fee 

embedded  inside  of  a  list  which  is  one  of  the  arguments.  This  is  an  inconvenient  requirement.  ' 

The  macro  PP:DEFINE -  FORMAT -DIRECTIVE  is  built  on  top  of  the  standard  macro  FORMAT :DEFFORMAT 
and  shares  many  of  the  latter  macro’s  idiosyncrasies  --  c.g.,  the  fact  that  when  a  user  defined  FORMAT  directive 
is  used  the  package  prefix  defaults  to  the  FORMAT  package.  The  macro  PP :  DEFINE -FORM  AT -DIRECTIVE  has 
two  advantages  over  the  macro  FORMAT :0EFF0RMAT.  First,  though  it  is  less  powerful,  it  is  simpler  to  use. 
Second,  the  function  implementing  the  FORMAT  directive  defined  takes  all  of  its  inputs  as  functional 
arguments,  rather  than  as  free  variable  inputs. 
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Checking  for  Malformed  Argument  Lists 

A  problem  with  FORMAT  arises  when  a  directive  is  used  to  iterate  over  a  list  argument  which  has  a 

non-NIL  atomic  CDR.  This  is  illustrated  in  the  example  below  which  generates  an  error  trying  to  take  the  CAR 
of  2. 

(FORMAT  T  "(~{~S~A  *(l  .  2)) 

The  problem  is  that,  using  the  standard  FORMAT  directives,  there  is  no  way  to  detect  when  a  non-NIL 
atomic  CDf;  is  encountered.  The  ~A  directive  tests  only  whether  the  argument  list  has  been  reduced  to  nil.  In 
order  to  d  ial  with  this  problem,  ~A  has  its  meaning  altered  slightly  when  it  is  encountered  in  a  logical  block. 
In  additio  i  to  testing  whether  the  argument  list  is  exhausted,  it  checks  to  see  if  the  argument  list  has  been 
reduced  to  a  non-NIL  atom.  If  checking  reveals  that  the  argument  list  has  become  a  non-NIL  atom  then 
"  .  "  is  printed  followed  by  the  atomic  value  and  the  processing  of  the  body  of  the  immediately  enclosing 
logical  block  is  terminated.  Any  suffix  which  has  been  specified  for  the  logical  block  is  printed.  The  effects  of 
this  check  are  illustrated  in  the  example  below. 

( FORMAT  T  "~11~S~A  ~S~.M  '(1  .  2)) 

The  call  on  FORMAT  produces  the  following  output 

(1  .  2) 

Note  that  the  check  for  a  non-NIL  atomic  argument  list  is  performed  even  though  pretty  printing  is  not 
triggered  in  this  example. 

Ihe  check  for  a  non-NIL  atomic  argument  list  is  particularly  useful  during  debugging  because  it  makes  it 
possible  for  a  FORMAT  control  string  to  execute  without  error  and  produce  informative  output  even  when  its 
arguments  are  malformed. 
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Unconditional  Newlines  in  a  Logical  Block 

If  encountered  in  a  logical  block  when  *PRINT-PRETTY»  is  T,  the  standard  FORMAT  directive  ~X 
(unconditional  newline)  has  its  meaning  altered  slightly.  In  addition  to  unconditionally  inserting  newlines  in 
the  normal  way,  indentation  is  used  (and  any  per-line  prefixes  are  inserted)  just  as  with  the  directive. 

The  pretty  printing  algorithm  is  also  somewhat  modified  in  order  to  take  account  of  ~X.  The  inclusion  of  a 
~X  directive  in  a  logical  block  prevents  the  block  from  being  printed  on  a  single  line.  In  order  to  deal  with  this 
aesthetically  when  pretty  printing,  a  logical  block  is  automatically  printed  in  multi-line  mode  whenever  it 
contains  a  directive. 

As  an  example  of  the  above,  consider  the  following  call  on  FORMAT. 

(FORMAT  T  "Roads  ; ELM  -XMAIN  ~_MAPLE~.”) 

The  output  below  will  be  produced  no  matter  how  much  line  width  is  available  for  printing. 

Roads  ;ELM 
;MAIN 
; MAPLE 

Note  that  forces  the  insertion  of  a  newline  even  when  not  pretty  printing.  In  this  case  a  -X  directive 
will  not  cause  a  logical  block  to  be  printed  in  multi-line  mode.  However,  indentation  and  any  per-line  prefix 
will  still  be  printed  after  the  newline  caused  by  the  -X.  As  a  result,  the  following  output  would  have  been 
produced  if  the  colon  flag  had  not  been  used  with  the  ~  1 ...  - .  directive  above. 

Roads  ; ELM 

;MAIN  MAPLE 

If  encountered  in  a  logical  block  when  *PRINT-PRETTY*  is  T,  the  standard  FORMAT  directive  (fresh 
line)  has  its  meaning  altered  in  the  same  way  as  ~X.  If  it  causes  the  insertion  of  a  newline,  then  indentation  is 
used  and  the  containing  logical  blocks  are  printed  in  multi-line  mode.  In  addition,  the  computation  of  when 
to  insert  a  newline  at  a  directive  is  altered  so  that  it  operates  with  respect  to  the  immediately  containing 
logical  block.  A  newline  is  inserted  only  if  some  characters  other  than  indentation  and  the  prefix  have  been 
output  in  the  block  since  the  last  newline.  This  is  illustrated  by  the  following  example  which  produces  the 
same  output  as  the  last  example. 

(FORMAT  T  "Roads  ~:!;~0;~&ELM  -&MAIN  ~_MAPLE~,") 
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Interaction  With  the  Standard  Format  Directives 

All  of  the  standard  FORMAT  directives  can  be  used  in  conjunction  with  the  new  directives  described  above. 

It  should  be  noted  that  the  standard  FORMAT  directives  -A  and  ~S  are  sensitive  to  the  variable 

•  PRINT- pretty*  and  will  therefore  do  pretty  printing  when  used  inside-:  I . . 

A  few  of  the  standard  FORMAT  directives  have  dynamic  formatting  capabilities.  For  example,  the  directive 
— <  conditionally  inserts  a  newline  with  a  prefix,  and  the  directive  uses  indentation 

when  printing.  These  directives  are  largely  rendered  obsolete  by  the  new  directives  introduced  above. 

Three  of  the  standard  FORMAT  directives  have  been  modified  so  that  they  will  fit  in  better  with  pretty 
printing.  'ILicse  are  discussed  in  the  following  two  subsections. 

Tabbing  Within  a  Logical  Block 

If  enccuntercd  in  a  logical  block,  the  standard  FORMAT  directive  ~T  is  altered  in  its  behavior.  In  this 

situation,  -T  acts  the  same  as  normal  except  that  it  spaces  relative  to  the  beginning  of  the  immediately 

containing  logical  block  section,  rather  than  with  respect  to  the  beginning  of  the  line  as  a  whole.  In  addition, 
while  the  i  tsign  flag  is  supported,  the  colon  flag  for  ~T  is  not  supported  in  a  logical  block. 

As  an  example  of  using  ~T  in  a  logical  block,  consider  the  following  call  on  FORMAT.  Each  street  name  is 
followed  ty  a  space  and  a  ~8T  which  ensures  that  the  total  width  taken  up  will  be  8.  If-needed  conditional 
newlines  are  used  to  put  as  many  streets  as  possible  on  each  line. 

(FORMAT  T  "Roads  ~:!~0{~S~a  ~8T~:_~}~.”  ' (ELM  MAIN  MAPLE  CENTER)) 

If  the  line  width  is  25,  this  will  print  in  two  columns  as  shown  below. 

Roads  ELM  MAIN 

MAPLE  CENTER 

The  change  in  meaning  of  ~T  in  a  logical  block  has  two  advantages.  First,  because  it  operates  within  a 
logical  block  section,  it  is  independent  of  whatever  indentation  is  in  effecL  In  the  example  above,  a  column 
spacing  of  8  is  used,  but  the  entire  table  is  shifted  over  6  columns  due  to  the  indentation  of  the  logical  block  as 
a  whole.  Second,  at  the  time  of  this  writing,  an  unfortunate  aspect  of  the  standard  ~T  directive  is  that  it  only 
does  tabbing  when  the  output  stream  supports  the  messages  :READ-CURSORPOS  and  :SET-CURS0RP0S  and 
yet  many  streams  do  not  support  these  messages.  The  changed  meaning  of  -T  gets  around  this  problem 
because  it  can  be  handled  internally  by  the  pretty  printing  algorithm  without  using  these  messages. 
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Miser  Mode  Conditional  Newlines 

In  order  to  give  the  user  greater  control  over  how  a  logical  block  will  be  printed  in  miser  mode,  PP 
provides  a  third  kind  of  conditional  newline  called  a  miser  mode  conditional  newline.  A  newline  is  inserted  at 
a  miser  mode  conditional  newline  if  and  only  if  the  immediately  containing  logical  block  is  being  printed  in 
miser  mode.  A  miser  mode  conditional  newline  can  be  specified  by  using  the  FORMAT  directive  ~0_.  If  a  ~0_ 
directive  is  encountered  outside  of  a  logical  block,  it  is  ignored.  The  example  below  is  the  same  as  the  one  in 
the  last  subsection  except  that  a  miser  mode  newline  directive  has  been  placed  before  the  function  name. 

(FORMAT  T  "~1 : !~S  ~:I~0_~S  ~:_~S  ~2I~_~S~."  ’(DEFUN  PRODUCT  (X  Y)  (*  X  Y)))  , 

In  this  case,  if  the  line  width  available  were  25  and  less  than  PP: *PRIMT-MISER-WIDTH*,  the  output 
would  be  printed  as  shown  below,  further  reducing  the  line  width  needed. 

(DEFUN 
PRODUCT 
(X  Y) 

(*  X  Y)) 

Pretty  Printing  as  Selection 

Stepping  back  a  moment,  it  is  useful  to  reflect  on  how  the  FORMAT  directives  above  interact  in  order  to 
support  pretty  printing.  The  directives  in  a  FORMAT  control  string  divide  the  output  up  into  a 

hierarchy  of  logical  blocks.  The  and  ~I  directives  simultaneously  specify  three  ways  (single-line  mode, 
multi-line  mode,  and  miser  mode)  in  which  each  logical  block  can  be  printed.  The  job  of  the  pretty  printer 
boils  down  to  selecting  (based  on  the  values  of  *PRINT-PRETTY*  and  PP:  *PRINT-MISER-WIDTH*,  on  the 
length  of  the  block,  and  on  the  line  width  available  for  printing)  which  of  the  three  modes  each  logical  block 
will  be  printed  in. 

The  FORMAT  directives  have  been  designed  so  that  it  is  relatively  easy  to  specify  three  different  ways  to 
print  a  logical  block  in  a  single  FORMAT  control  string.  None  of  the  special  FORMAT  directives  generate  any 
output  other  than  prefixes,  suffixes,  newlines,  and  indentation.  The  characters  to  be  output  in  each  logical 
block  section  are  determined  solely  by  the  rest  of  the  FORMAT  control  string  and  are  exactly  the  same  in  each 
of  the  three  modes.  The  and  ~I  directives  specify  how  the  logical  block  sections  are  to  be  arranged  in 
multi-line  mode  and  miser  mode.  A  certain  amount  of  care  has  to  be  taken  to  make  sure  that  output  is 
aesthetic  in  both  of  these  modes. 

There  arc  many  other  kinds  of  pretty  printing  directives  which  could  have  been  supported  --  for  example, 
sections  of  text  which  are  output  only  in  multi-line  mode.  The  PP  system  supports  only  the  limited  setpf 

v 

directives  above  because,  experience  has  shown  them  to  be  a  good  compromise  between  the  requirements  of 
expressive  power,  easy  understandability,  and  efficiency. 
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Miser  Mode 

A  fundamental  problem  with  pretty  printing  arises  when  printing  very  large  structures.  As  the  pretty 
printer  is  forced  to  print  more  and  more  deeply  nested  logical  blocks  in  multi-line  mode,  the  indentation  gets 
greater  and  greater.  This  causes  the  line  width  available  for  printing  to  get  smaller  and  smaller  until  it  is  no 
longer  possible  to  print  substructures  in  the  space  allowed. 

An  approach  to  dealing  with  this  problem  which  has  been  used  at  least  since  the  original  Gcldstein  pretty 
printer  [  1)  is  to  introduce  a  special  compact  kind  of  multi-line  mode  (called  miser  mode)  and  to  use  this  mode 
once  the  1  ne  width  begins  to  get  small.  The  key  idea  behind  miser  mode  is  that  by  trading  off  readability  for 
compactness  it  reduces  the  width  necessary  for  printing  a  logical  block,  and  even  more  importantly,  it  reduces 
the  indexation  required  for  printing  the  output  lines  in  the  block. 

In  the  pp  system,  the  use  of  miser  mode  is  controlled  by  the  variable  PP: •PRINT-MISER-WlOTH*.  Miser 
mode  is  used  instead  of  ordinary  multi-line  mode  whenever  the  line  width  available  is  less  than  the  value  of 
PP:  *PRlf it -MISER-WIDTH*.  Single-line  mode  is  always  used  when  a  logical  block  can  fit  in  the  line  width 
available.  If  pp  :  *PRlNT-MISER-WlDrH«  is  given  the  value  NIL  then  miser  mode  will  never  be  used. 

Miser  mode  has  two  major  effects  on  the  way  a  logical  block  is  printed.  First,  newlines  are  inserted  at 
every  if-needed  conditional  newline  as  well  as  at  every  multi-line  mode  conditional  newline.  Second,  all  ~I 
directives  are  ignored,  thereby  forcing  the  lines  corresponding  to  the  logical  block  to  line  up  under  the  first 
character  in  the  block  after  the  prefix.  Consider  again  the  example  (reproduced  below)  used  in  the  last 
subsection. 

(FORMAT  T  "~1 : I~S  ~:I~S  ~:_~S  '(DEFUN  PRODUCT  (X  Y)  (•  X  Y))) 

If  die  line  width  available  were  25  and  less  than  PP :  *PRINT-MISER-WIDTH*,  the  output  would  be  printed  as 
shown  below.  (For  simplicity,  the  examples  in  this  paper  always  assume  that  miser  mode  printing  is  not 
triggered,  unless  it  is  explicitly  stated  otherwise.) 

(DEFUN  PRODUCT 
(X  Y) 

(•  X  Y)) 

The  variable  PP :  *  PR  I  NT -MISER-WIDTH*  has  a  default  value  of  40.  A  constant  value  irrespective  of  line 
length  is  used  because  die  point  at  which  miser  mode  should  be  triggered  docs  not  depend  on  the  line  length, 
but  rather  on  how  long  the  logical  block  sections  between  conditional  newline  positions  arc  in  the  output 
being  prnted.  When  pretty  printing  programs  the  distance  between  conditional  newlines  depends  on  the 
lengths  ef  the  symbols  in  the  program.  Experience  suggests  that  PP:  *PRINT-MISER-WIDTH*  should  be  set  at 
from  twe  to  four  dmes  the  length  of  the  typical  symbol  being  printed. 

Even  in  miser  mode,  the  pretty  printing  algorithm  used  by  PP  is  not  guaranteed  to  succeed  in  keeping  its 
output  v  ithin  the  line  width  available.  The  pretty  printing  algorithm  never  inserts  newlines  other  than  at 
conditional  newline  positions.  As  a  result,  a  given  output  requires  a  certain  minimum  amount  of  line  width  in 
order  to  print  it  (e.g.,  a  width  of  14  in  the  example  above).  If  the  amount  of  line  width  available  is  less  than 
this  amo  .int,  the  pretty  printing  algorithm  simply  prints  characters  beyond  the  end  of  the  line. 

The  ';print  system  supported  an  additional  mechanism  for  dealing  with  the  problem  of  running  out  of 
line  widih  when  pretty  printing  deeply  nested  structures.  When  indentation  reduced  the  line  width  to  a  small 
percentage  of  its  initial  value,  major  program  structures  (such  as  PROGs  and  LETs)  were  shifted  to  the  left  by 
reducing  the  indentation.  This  violated  standard  Lisp  pretty  printing  style,  but  significantly  i  icrcascd  the  line 
width  available  for  printing.  Experience  showed  that  though  this  was  very  useful  in  some  situations,  it  was,  in 
general,  more  confusing  than  helpful.  As  a  result,  this  feature  was  not  included  in  the  PP  system. 
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Indentation 

As  mentioned  above,  the  second  and  subsequent  output  lines  corresponding  to  a  logical  block  are 
indented  so  that  they  line  up  vertically  under  the  column  position  of  the  first  character  in  the  block  after  the 
prefix.  Thv  fORMAT  directive  ~I  makes  it  possible  to  specify  a  different  indentation.  The  directive  ~nl 
specifies  that  the  indentation  should  be  set  to  the  column  position  of  the  first  character  after  the  prefix  plus  n. 
The  directive  ~n:  I  specifies  that  the  indentation  should  be  set  to  the  column  position  in  the  output  of  the 
~n:  I  directive  itself,  plus  n.  If  omitted,  the  parameter  n  defaults  to  zero.  The  parameter  can  be  negative,  but 
the  indentation  cannot  be  set  at  less  than  the  position  of  the  first  character  after  the  prefix.  If  a  ~I  directive  is 
encountered  outside  of  a  logical  block,  it  is  ignored.  As  an  example  of  using  -I,  consider  the  following. 

(FORMAT  T  "~1 : 1 ~S  ~:I~S  ~:_~S  '(DEFUN  PRODUCT  (X  Y)  (*  X  Y))) 

If  the  line  width  available  is  25,  multi-line  mode  will  be  used  and  a  newline  will  be  inserted  at  the 
multi-line  mode  conditional  newline  as  shown  below.  The  directive  ~ll  specifies  that  the  statement  in  the 
body  of  the  DEFUN  should  be  printed  at  a  relative  indentation  of  1  in  the  logical  block.  Note  that  an  open 
parenthesis  is  used  as  a  prefix  in  the  logical  block,  and  therefore  the  total  indentation  is  2. 

(DEFUN  PRODUCT  (X  Y) 

(•  X  Y)) 

If  the  line  width  is  less  than  21,  a  newline  will  also  be  inserted  at  the  if-needed  conditional  newline  before 
the  argument  list  as  shown  below.  The  directive  ~ :  I  before  the  function  name  causes  the  argument  list  to  be 
lined  up  under  the  name.  Notice  that  the  column  position  corresponding  to  the  I  directive  is  determined 
dynamically  as  the  output  is  produced. 

(DEFUN  PRODUCT 
(X  Y) 

(•  X  Y) ) 

Changes  in  relative  indentation  caused  by  a  ~l  directive  do  not  take  effect  until  after  the  next  newline  is 
printed.  As  a  result,  it  is  important  that  the  -  II  directive  in  the  call  on  FORMAT  above  precede  the  directive 
after  the  argument  list.  In  addition,  a  -I  directive  only  affects  the  indentation  in  the  immediately  containing 
logical  block. 
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Filling 

If-needed  conditional  newlines  can  be  used  when  outputting  text  in  order  to  make  the  text  aesthetically  fill 
the  space  available.  For  example,  consider  the  call  on  FERROR  used  as  an  example  above.  'Die  FORMAT 
control  string  specifies  only  one  place  where  a  newline  can  be  inserted  in  the  error  message.  As  a  result,  a 
minimum  line  width  of  45  is  required  to  print  it.  The  example  below  shows  how  the  FORMAT  control  string 
can  be  modified  so  that  the  error  message  will  print  aesthetically  on  shorter  line  lengths. 

( F ERROR  :~0;Bound  ~:_variable  ~:_~S  ~:_1s  ~:_not  ~:_a 

symbol  ~:_1n  " 

2  '(LET  ((2  X-VALUE))  (+  X-VALUE  X-VALUE))) 

An  if-n  ceded  conditional  newline  is  placed  between  each  pair  of  words  in  the  error  message.  This  causes 
the  pretty  printer  to  dynamically  decide  where  to  place  newlines  in  order  to  cause  the  error  message  to  fill  the 
line  width  available.  If  the  modified  call  on  FERROR  is  evaluated  with  a  line  length  of  30  then  the  following 
output  is  produced. 


»Er  'or : 


Bound  variable  2  Is 
not  a  symbol  In 
(LET  ((2  X-VALUE)) 
(+  X-VALUE 
X-VALUE)). 


FORMAT  control  strings  like  the  one  above  are  very  useful  but  they  are  difficult  to  read  and  write  due  to  the 
presence  of  so  many  directives.  A  special  form  of  the  ~l . . .~.  directive  is  provided  which  makes  it 
easier  to  specify  such  FORMAT  control  strings.  If  the  atsign  flag  is  used  with  the  directive  (i.e.,  -0 ;  or  ~0 . )  that 
marks  the  end  of  the  body  in  a  ~1 . . .~.  directive  then  the  body  is  modified  by  automatically  inserting 
directives  after  each  chunk  of  which  space  (except  for  white  space  after  a  ~<newllne>  directive).  The 
example  below  shows  the  use  of  this  feature.  It  is  exactly  equivalent  to  the  example  above. 

(FERROR  "~:0I ;~@;Bound  variable  ~S  Is  not  a  ~ 
symbol  in  ~S.~0." 

2  '(LET  ((2  X-VALUE))  (+  X-VALUE  X-VALUE))) 
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Tailoring  the  Pretty  Printer 

An  important  aspect  of  generalized  print-self  functions  is  that  they  serve  as  a  general  mechanism  for 
tailoring  the  pretty  printer.  For  example,  the  pretty  printer  prints  lists  with  non-atomic  CAFs  using  the 
directive  ~\F  ILIA.  Suppose  that  a  user  wanted  to  have  lists  with  non-atomic  CARS  printed  using  ~\LINEAR\ 
instead.  Ths  change  could  be  made  by  enabling  the  following  generalized  print-self  method. 

(n-:DEFINE-G£NERALIZED-PRINT-FUNCTION  LINEAR-LISTS  (OBJ  STREAM) 

(ANO  ( LISTP  OBJ)  (NOT  (ATOM  (CAR  OBJ)))) 

(PP: FAST-FORMAT  STREAM  ”~1\LINEARV’  OBJ)) 

As  a  more  interesting  example,  suppose  that  the  user  wanted  lists  with  non-atomic  CARS  to  be  printed 
using  ~\F I _L\  in  general,  but  wanted  ~\LIN£AR\  to  be  used  when  a  list  with  a  non-atomic  CAR  occurred 
inside  a  quoted  structure.  This  change  could  be  made  be  using  the  following  list  print-self  function  for 
QUOTE.  'Hie  list  print-self  function  makes  the  change  by  selectively  enabling  the  generalized  print-self 
function  LINEAR-LISTS  only  when  printing  a  quoted  structure, 

( PP :DEF INE -LIST- PR INT -FUNCTION  QUOTE  (LIST  STREAM) 

(COND  ((AND  (LISTP  (COR  LIST))  (NULL  (CDDR  LIST))) 

(PP : WITH- GENERAL  I  ZED- PR INT- FUNCTION  LINEAR-LISTS 
( PP : FAST-FORMAT  STREAM  '"-W"  (CADR  LIST)))) 

(T  ( PP : FAST-FORMAT  STREAM  "~1\FILL\"  LIST)))) 

Generalized  print-self  functions  can  be  very  useful.  However,  since  every  enabled  generalized  print-self 
function  must  be  tested  against  every  object  to  be  pretty  printed,  the  generalized  print-self  mechanism  is 
rather  inefficient.  It  is  suggested  that  generalized  print-self  functions,  only  be  locally  enabled  (using 
pp  :  WITH -GENERALI  ZED- PR  I  NT -FUNCTION)  where  specifically  needed.  In  general,  globally  activating  a 
generalized  print-self  function  is  only  reasonable  during  debugging. 
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V  -  Abbreviation 

This  section  describes  the  way  the  PP  system  handles  the  abbreviation  of  output.  Abbreviation  of  output 
based  on  the  length  and  depth  of  nested  structures  is  supported  both  during  ordinary  printing  and  during 
pretty  printing.  The  way  they  are  supported  is  changed  so  that  they  are  automatically  applied  to  every  kind  of 
structure  without  the  program  writer  having  to  take  any  explicit  action  when  writing  a  print-self  method.  In 
addition,  a  new  kind  of  abbreviation  is  introduced  which  can  be  used  to  limit  the  total  number  of  lines 
printed. 

Length  Abbreviation 

Length  abbreviation  is  controlled  by  die  variable  PR  INLENGTH.  (When  Common  Lisp  compatibility  is 
introduced  this  variable  will  be  called  *PRINT-LENGTH*.)  The  standard  output  functions  for  both  the  Lisp 
Machine  and  Common  Lisp  provide  no  automatic  support  for  length  abbreviation  except  that  the  internal 
function  for  printing  lists  performs  abbreviation  when  it  is  appropriate.  If  a  user  wants  to  support  length 
abbreviation  in  a  print-self  method,  then  he  has  to  consult  the  value  of  PRINLENGTH  and  print  an  abbreviation 
marker  when  appropriate.  However,  due  to  the  difficulty  of  actually  doing  this,  print-self  methods  seldom 
support  length  abbreviation.  Therefore,  as  a  practical  matter,  length  abbreviation  is  only  supported  for  lists. 

The  PP  system  handles  lengdi  abbreviation  in  a  different  way.  Length  abbreviation  is  handled 
automatically  based  on  the  number  of  sections  that  are  printed  inside  of  a  logical  block.  As  a  result,  the  writer 
of  a  print-self  method  need  not  take  any  action  at  all,  other  than  specifying  logical  blocks,  in  order  to  support 
length  abbreviation. 

Each  time  a  ~%,  or  directive  ending  a  logical  block  section  is  encountered  the  PP  system  checks  how 
many  sections  have  been  printed  inside  of  the  current  logical  block.  If  PR  inlength  sections  have  been 
printed,  then  ",  . ."  is  printed  and  the  processing  of  the  body  of  the  immediately  enclosing  logical  block  is 
terminated.  Any  suffix  which  has  been  specified  for  the  logical  block  is  printed.  As  an  example  of  how  length 
abbreviation  works,  consider  the  print-self  method  (reproduced  below)  for  the  flavor  called  FAMILY. 

( PP : DEF INE-FORMAT-OIRECTIVE  FORMAT:FILL  (LIST  STREAM  IGNORE  IGNORE 

&0PTI0NAL  (PARENS?  0)) 

( PP : FAST- FORMAT  STREAM  "~V!~0{~W~A  PARENS?  LIST)) 

( DE  FMETHOD  (FAMILY  :  PRINT-SELF  )  (STREAM  &REST  IGNORE) 

( PP : FAST-FORMAT  STREAM  "~@ ! #<- ; FAMILY  -  IMOTHER  ~W  -.CHILDREN  ~1\FILL\~ ; >~ . ” 

MOTHER  CHILDREN)) 

Executing  (print  f)  with  PRINLENGTH  set  to  1  produces  the  following. 

#< FAMILY  -  MOTHER  "Lucy"  ...> 

Executing  (PRINT  F)  with  PRINLENGTH  set  to  2  produces  the  following. 

AKFAMILY  -  MOTHER  "Lucy"  CHILDREN  ("Mark"  "Barbara”  ...)> 

Length  abbreviation  is  automatically  supported  everywhere  logical  blocks  arc  used.  This  is  the  case  even 
when  •PRINT-PRETTY*  is  NIL.  Length  abbreviation  can  be  prevented  by  binding  PRINLENGTH  to  NIL  (c.g., 
by  using  the  colon  flag  with  ~w). 


PP:  A  Lisp  Pretty  Printing  System 


27 


L  • 

yv 

v  • 
i  • 
K'.- 

* 

r" 

l-  ' 

r 

r- 


i,  • 

\  ’ 


i 


N 


« 


V 


Depth  Abbreviation 

Depth  Abbreviation  is  controlled  by  the  variable  PR  INLEVEL.  (When  Common  Lisp  compatibility  is 
introduced  this  variable  will  be  called  *PRINT-LEVEL*.)  The  standard  output  functions  for  both  the  Lisp 
Machine  a  id  Common  Lisp  handle  depth  abbreviation  by  passing  around  a  parameter  which  specifics  the 
printing  depth  at  each  level  in  the  structure  being  printed.  In  order  to  fit  in  with  this  scheme,  print-self 
methods  are  passed  a  printing  depth  argument  and  arc  expected  to  handle  it  appropriately  --  e.g ,  to  print  out 
a  depth  abbreviation  marker  when  necessary,  and  to  pass  along  an  incremented  depth  counter  when  printing 
the  subparts  of  a  structure.  However,  due  to  the  difficulty  of  actually  doing  this,  print-self  methods  typically 
ignore  the  r  printing  depth  argument.  Therefore,  as  a  practical  matter,  depth  abbreviation  is  only  supported 
by  the  standard  printer  for  nested  lists. 

The  Pf  system  handles  depth  abbreviation  in  a  different  way.  Rather  than  passing  around  a  depth 
counter,  d:pth  abbreviation  is  handled  based  on  the  dynamic  nesting  of  logical  blocks  in  the  output.  As  a 
result,  die  writer  of  a  print-self  method  need  not  take  any  action  at  all,  other  than  specifying  logical  blocks,  in 
order  to  support  depth  abbreviation. 

If  a  log  cal  block  is  started  at  a  dynamic  nesting  depth  of  PRINLEVEL  in  logical  blocks,  then  •  >  is  printed  in 
the  output,  and  execution  goes  to  after  the  end  of  the  logical  block  -  skipping  the  computation  of  what  to 
print  in  the  block.  (When  Common  Lisp  compatibility  is  introduced  #  will  be  printed  in  the  output.)  Note 
that  the  c  ynamic  nesting  depth  of  a  logical  block  is  not  the  static  nesting  depth  of  the  corresponding 
-  t . . .  ~ .  directive  in  its  format  control  string,  but  the  total  depth  in  the  output.  As  an  example  of  how  depth 
abbreviation  works,  consider  again  the  print-self  method  (reproduced  below)  for  the  flavor  called  FAMILY. 

(PP : DEFINE -FORMAT -DIRECTIVE  FORMAT : FILL  (LIST  STREAM  IGNORE  IGNORE 

&0PTI0NAL  (PARENS?  0)) 

( PP : FAST- FORMAT  STREAM  "~VI~0{~W~A  PARENS?  LIST)) 

(DEFMETHOD  (FAMILY  :PRINT-SELF)  (STREAM  &REST  IGNORE) 

(PP : FAST- FORMAT  STREAM  ! #<- ; FAMILY  -  IMOTHER  -W  -.CHILDREN  ~1\FILL\~;>~. " 

MOTHER  CHILDREN)) 

Executing  (print  f)  with  PRINLEVEL  set  to  1  produces  the  following.  The  list  of  children  is  abbreviated 
to  ••  because,  when  ~\fill\  is  called  to  print  the  list  it  attempts  to  start  a  logical  block  at  a  dynamic  nesting 
depth  of  1  !  be  string  "Lucy"  is  not  abbreviated  because  no  logical  block  is  created  when  it  is  printed. 

/KFAMIl.Y  -  MOTHER  "Lucy"  CHILDREN  ••> 

Suppo.c  that  the  list  of  children  were  changed  to  (("Mark")  "Barbara").  Executing  (PRINT  F)  with 
prinlfvel  set  to  2  would  produce  the  following. 

HKFAMILY  -  MOTHER  "Lucy"  CHILDREN  (•«  "Barbara")> 

Depth  abbreviation  is  automatically  supported  everywhere  logical  blocks  are  used.  This  is  the  case  even 
when  .print-pretty*  is  NIL.  Depth  abbreviation  can  be  prevented  by  binding  PRINLEVEL  to  NIL  (e.g.,  by 
using  the  colon  flag  with  ~W). 

For  co  nplctcncss,  die  PP  output  functions  pass  an  appropriate  depth  counter  value  to  print-self  methods, 
however  mere  is  no  reason  for  a  print-self  method  to  do  anything  with  it.  In  the  interest  of  simplicity,  no 
depth  cou  nter  argument  is  passed  to  list  print-self  functions,  generalized  print-self  functions,  o:  user-defined 
FORMA!  d  recti vcs. 
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Abbreviation  Based  on  the  Number  of  Lines  Printed 

In  addition  to  the  traditional  abbreviation  mechanisms.  PP  provides  a  new  abbreviation  mechanism  which 
can  be  used  to  limit  the  number  of  lines  printed.  When  non-NIL,  the  variable  PP:  •PRINT-LINES*  controls 
the  number  of  lines  which  can  be  printed  by  an  outermost  logical  block.  If  an  attempt  is  made  to  print  more 
than  PP :  ‘PRINT-LINES*  lines  in  an  outermost  logical  block,  then  "  ---"is  printed  at  the  end  of  the  last  line 
and  the  outermost  logical  block  is  immediately  exited.  In  order  to  insure  that  printing  can  never  go  beyond 
the  end  of  the  last  line,  any  pending  suffixes  are  not  printed. 

As  an  example  of  abbreviation  based  on  the  number  of  lines  printed,  consider  the  following.  k 

(LET  ( ( PP : ‘PRINT-LINES*  3))  ? 

(PPRINT  ’ (SETQ  A  1  B  2  C  3  0  4})) 

This  call  on  PPRINT  produces  the  output  below. 

(SETQ  A  1 
8  2 

C  3  --- 

Abbreviation  based  on  the  number  of  lines  printed  is  automatically  supported  everywhere  logical  blocks 
are  used.  This  is  the  case  even  when  *PRINT-PRETTY«  is  NIL.  (However,  it  should  be  noted  that  ordinary 
printing  usually  creates  only  a  single  line  of  output  --  which  may  be  very  long.)  This  abbreviation  can  be 
prevented  by  binding  *PRINT-LINES*  to  NIL,  which  is  its  default  value  (e.g.,  by  using  the  colon  flag  with  ~W). 

Extensive  experience  with  the  earlier  GPRINT  system  has  shown  that  abbreviation  based  on  the  number  of 
lines  printed  can  be  much  more  useful  than  the  traditional  depth  and  length  abbreviation  mechanisms.  This 
is  particularly  true  when  the  user  wants  to  limit  output  to  a  small  space.  In  order  to  do  this  with  depth  and 
length  abbreviation,  the  length,  and  more  significantly  the  depth,  have  to  be  limited  to  very  small  values  such 
as  3  or  4.  This  has  the  unfortunate  effect  of  often  producing  output  which  consists  almost  totally  of  "••"sand 
"...  "s  grouped  in  parentheses.  In  contrast,  limiting  the  total  number  of  lines  printed  to  3  or  2  or  even  1 
produces  a  more  legible  output.  Simply  put,  seeing  the  first  few  lines  of  output  is  usually  more  informative 
then  seeing  only  the  top  level  skeletal  structure  of  the  output. 

Reprinting  an  Abbreviated  Object 

When  an  object  is  abbreviated  due  to  ‘PRINT-LINES*  while  being  printed  by  PP:  INTERACTIVE -WRITE, 
the  object  is  saved.  A  function  is  provided  which  can  be  used  to  reprint  a  saved  object  (or  any  other  object) 
without  any  abbreviation.  When  a  saved  object  is  reprinted,  an  attempt  is  made  to  overwrite  the  old  part^l 
output  with  the  full  output  in  order  to  save  screen  space.  Objects  are  saved  on  a  per  process  basis  so  that 
object  abbreviated  in  one  process  will  not  get  reprinted  in  another  process. 

PP:PP  &optional  object  stream 

This  is  the  same  as  PPRINT  except  that  it  prints  object  without  any  abbreviation.  The  object  defaults  to 

the  object  last  saved  because  it  was  abbreviated  by  PP:  INTERACTIVE-WRITE  due  to  *PRINT-LINE$«. 

Typing  the  Lisp  Machine  interrupt  sequence  <FUNCTI0N>  <RESUME>  evaluates  the  expression  ( PP :  PP)  in 
the  current  process. 
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VI  -  Conclusion 

Reduced  to  its  essence,  PP  embodies  a  few  key  ideas.  These  ideas  transcend  the  system  itself  and  could  be 
used  in  almost  any  output  system.  In  general,  these  ideas  arc  relatively  independent  and  a  given  output 
system  could  pick  and  choose  among  them.  However,  careful  design  is  needed  in  order  for  all  the  ideas  to  fit 
together  into  a  coherent  whole. 

The  concept  of  logical  blocks  and  conditional  newlines  provides  a  straightforward  way  for  the  writer  of  an 
output  expression  to  deal  reasonably  aesthetically  with  two  important  kinds  of  variability.  Variability  in  line 
length  ava  lable  for  output,  and  variability  in  the  sizes  of  the  items  being  printed.  The  way  PP  adds  logical 
blocks  anc  conditional  newlines  into  the  standard  Lisp  FORMAT  construct  demonstrates  that  logical  blocks  and 
condition.'  1  newlines  are  orthogonal  to  most  other  output  concepts  and  can  be  relatively  easily  integrated  with 
them.  The  same  would  be  true  in  virtually  any  programming  environment. 

PP  extends  the  idea  of  having  each  object  know  how  to  print  itself  to  lists.  This  provides  a  basis  which 
makes  it  etsy  to  implement  traditional  pretty  printing  of  Lisp  programs.  It  also  makes  it  easy  for  a  given  user 
to  control  the  way  his  programs  pretty  print.  This  idea  could  be  used  straightforwardly  in  any  programming 
environment  where  a  data  structure  representing  program  parse  trees  has  been  defined. 

The  closely  related  idea  of  generalized  print-self  functions  provides  a  means  for  specifying  how  to  print 
arbitrary  c  bjccts.  It  also  serves  as  a  basis  for  tailoring  the  pretty  printer  in  arbitrary  ways. 

An  important  philosophy  underlying  PP  is  that  facilities  should  be  provided  so  that  a  single  output 
expression  (e.g.,  FORMAT  control  string)  can  specify  how  to  print  something  in  each  of  the  standard  printing 
styles  (i.e.,  with  or  without  escape  characters  and  with  or  without  pretty  printing)  without  having  to  force 
which  style  will  be  used.  This  gives  the  end  user  maximal  flexibility  in  requesting  different  ways  to  print 
something.  This  philosophy  is  most  evident  in  die  fact  that  the  FORMAT  directive  ~W  does  not  force  the 
printing  of  escape  characters,  and  the  directives  ~  t . . .  ~ .  and  do  not  force  pretty  printing. 

Depth  and  length  abbreviation  is  applied  to  all  output  in  a  uniform  way.  This  is  done  by  giving  depth  and 
length  abbreviation  a  simple  definition  in  terms  of  logical  blocks  and  logical  block  sections.  This  allows  PP  to 
support  abbreviation  for  all  output  without  the  user  having  to  write  any  explicit  code  to  support  it 

A  new  kind  of  abbreviation  is  introduced  which  can  be  used  to  limit  the  total  number  of  lines  printed. 
Kxpcricnce  has  shown  that  in  many  situations  this  new  abbreviation  is  more  useful  than  depth  and  length 
abbrev  iation.  This  utility  is  enhanced  by  the  availability  of  a  mechanism  for  easily  reprinting  in  full  an  object 
which  war.  abbreviated  based  on  the  number  of  lines  printed. 

The  icea  of  having  separate  interactive  output  control  variables  is  introduced  so  that  a  user  can  specify 
what  style  should  be  used  for  interactive  output  without  changing  the  default  style  which  will  be  used  for 
other  out  )ut.  This  is  particularly  useful  in  conjunction  with  abbreviation  which  is  typically  only  desirable 
during  interactive  output. 

An  important  fact  is  the  realization  that  pretty  printing  does  not  have  to  be  slow.  Because  it  is  based  on  a 
fast  line.v  algorithm,  the  pretty  printer  provided  by  PP  is  not  significantly  slower  than  the  ordinary  Lisp 
printer.  Given  that  pretty  printed  output  is  a  great  deal  more  legible  than  ordinary  output  there  is  little 
reason  not  to  make  pretty  printing  be  the  default  (at  least  for  interaction  with  the  user). 

Similarly,  FORMAT  does  not  have  to  be  slower  than  any  other  output  function  *-  it  can  in  general  be 
efficiently  compiled.  Most  languages  other  than  Lisp  have  always  compiled  their  FORMAT-like  statements. 
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Appendix  -  Second  Order  Details 

This  section  describes  a  number  of  details  which  are  important  in  order  to  gain  a  full  understanding  of  the 
pretty  printing  facilities  provided  by  the  PP  system,  but  which  are  not  important  for  the  casual  user. 

The  Pretty  Printing  Algorithm 

Section  III  outlined  the  basic  pretty  printing  algorithm  used  by  PP.  This  subsection  presents  a  number  of 
special  situations  and  boundary  conditions  which  are  not  covered  by  the  basic  algorithm  and  describes  how 
the  algori  hm  has  been  extended  to  deal  with  them. 

An  area  of  complexity  stems  from  the  interaction  of  logical  blocks  and  if-needed  conditional  newlines. 
Consider  the  cal!  on  FORMAT  below 

( FORMAT  T  "~1: 1-111  ~:_2  ~:_3~.  ~:_A 

Using  the  pretty  printing  algorithm  as  defined  above,  this  would  create  the  following  output  given  a  line 
width  of  tf.  The  list  (l  2  3)  has  to  be  printed  in  multi-line  mode  since  it  is  too  long  to  fit  on  one  line.  The 
clement  />  is  printed  at  the  end  of  the  second  output  line  since  there  is  room  for  it  there. 

((1  2 
3  >  A 

B) 

The  fact  that  A  appears  at  the  end  of  the  second  output  line  is  judged  by  many  people  to  violate  a  basic 
aesthetic  criterion  of  Lisp  pretty  printing.  In  order  to  deal  with  this  problem,  the  basic  pretty  printing 
algorithm  has  been  altered  so  that  a  newline  will  be  inserted  at  an  if-needed  conditional  newline  position 
whenever  the  logical  block  section  preceding  it  is  not  printed  on  a  single  line.  Applying  this  extended 
definition,  the  output  is  as  follows. 

((1  2 
3) 

A  8) 

Another  area  of  complexity  stems  from  the  fact  that  a  logical  block  is  often  followed  by  some  additional 
characteis  which  must  be  printed  on  the  same  line  as  the  logical  block.  These  characters  can  be  literal 
characters  such  as  the  " . "  in  the  call  on  FORMAT  below,  or  produced  by  FORMAT  directives. 

(FORMAT  T  (Roads  -IELM  ~_MAIN~. ”} 

If  the  innermost  logical  block  is  printed  on  one  line,  then  the  ” .  ”  will  also  have  to  be  printed  on  that  line. 
If  there  i .  only  barely  enough  room  for  the  logical  block  itself,  then  the  " . "  will  go  over  the  end  of  the  line.  In 
order  to  deal  with  this  problem,  the  decision  of  whether  to  use  single-line  mode  or  multi-line  mode  when 
printing  a  logical  block  (other  than  an  outermost  logical  block)  is  not  based  solely  on  the  length  of  the  logical 
block  its  .'If,  but  rather  on  the  length  of  the  block  plus  the  length  of  any  characters  which  must  be  printed  on 
the  same  line  after  it.  For  example,  the  call  on  FORMAT  above  produces  multi-line  mode  output  even  when  the 
line  widih  available  is  equal  to  14  --  i.e.,  just  long  enough  for  the  block  itself.  When  considering  outermost 
logical  b  ocks,  characters  that  follow  are  not  taken  into  account  because  the  special  printing  supported  by  PP 
is  no  Ion  ;cr  in  effect  after  die  end  of  an  outermost  logical  block. 

An  analogous  problem  arises  with  regard  to  if-nccdcd  newlines.  The  last  section  of  a  logical  block  can  be 
followed  by  characters  which  must  be  printed  after  it  on  the  same  line  --  i.e.,  characters  which  follow  the  block 
as  a  whole.  In  order  to  allow  for  this,  the  decision  of  whether  or  not  to  insert  a  newline  is  based  on  the  length 
of  the  logical  block  section  itself  plus  the  length  of  any  characters  which  must  be  printed  after  it  on  the  same 
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line  unless  they  follow  the  outermost  logical  block. 

A  final  area  of  complexity  stems  from  the  fact  that  there  are  many  ways  to  force  a  newline  in  a  FORMAT 
control  string  besides  using  the  directives  and  --  e.g.,  putting  a  literal  newline  character  in  the 

control  string  or  printing  a  string  w'hich  contains  a  newline  character.  It  is  not  completely  obvious  what  to  do 
in  this  situation.  There  arc  two  very  suggestive  cases  which  unfortunately  contradict  each  other.  First, 
suppose  that  a  program  which  contains  a  string  constant  which  contains  a  newline  character  is  printed  out  and 
then  read  back  in  again.  In  order  to  insure  that  the  result  of  the  read  will  be  EQUAL  to  the  original  program  it 
is  important  that  indentation  not  be  inserted  after  the  newline  character  in  the  string.  On  the  other  hand, 
suppose  that  the  same  program  is  being  printed  into  a  file  by  a  FORMAT  that  specifies  a  prefix  of  " ; ; ; "  with 
the  intention  that  the  program  will  appear  in  the  output  as  a  comment.  In  order  to  insure  that  this  comment 
will  not  interfere  with  subsequent  reading  from  the  file  it  is  important  that  the  prefix  be  printed  after  the 
newline  in  the  string. 

In  order  to  try  and  satisfy  the  intent  of  both  of  the  above  cases,  the  following  heuristic  is  applied, 
indentation  is  used  only  if  a  newline  is  created  with  ~X,  or  However,  per-line  prefixes  (and  any 
indentation  preceding  them)  arc  always  printed  whenever  a  newline  is  created  in  the  output  no  matter  how 
the  newline  is  specified.  This  heuristic  is  illustrated  in  the  example  below. 

(LET  ((X  '((STRING-LENGTH  "string  on 
two  lines")))) 

(FORMAT  T  1~VI~.  1 ; ; -XFor  example:  1 X  X  X)) 

This  expression  produces  the  following  output 

(STRING-LENGTH  "string  on 
two  lines") 

: ; ; (STRING-LENGTH  "string  on 
;  ;  ; two  lines") 

For  example:  ;  (STRING-LENGTH  "string  on 
;  two  lines") 

A  small  point  centers  around  the  fact  that  conditional  newline  specifications  are  typically  preceded  by 
some  amount  of  blank  space  (see  the  examples  above).  This  is  done  so  that  the  sections  of  a  logical  block  will 
be  visually  separated  when  the  block  is  printed  in  single-line  mode.  Without  anything  more  being  said,  this 
would  lead  to  the  printing  of  unnecessary  blank  spaces  at  the  end  of  most  lines  in  multi-line  mode.  In  the 
interest  of  efficiency,  the  pretty  printing  algorithm  suppresses  the  printing  of  blanks  at  the  end  of  a  line  if  (and 
only  if)  the  newline  ending  the  line  is  caused  by  a  variant  of  the  directive 

Some  implementation  Notes  and  Their  Implications 

The  pretty  printing  algorithm  is  implemented  in  two  parts.  The  first  part  is  a  modified  version  of  the 
standard  l.isp  Machine  function  SI :  PRINT-OBJECT  which  supports  dispatching  to  print-self  functions.  The 
second  part  is  a  special  kind  of  stream  which  is  wrapped  around  the  actual  output  stream.  This  intermediate 
stream  buffers  up  the  output  and  makes  the  dynamic  pretty  printing  decisions.  In  order  to  install  the  pretty 
printing  facilities  in  the  PP  system  as  a  basic  part  of  the  standard  Lisp  Machine  system,  all  that  would  be 
needed  would  be  to  replace  SI :  PRINT-OBJECT  with  its  modified  version  and  give  every  stream  the  capability 
to  pci  form  dynamic  pretty  printing  decisions. 

When  pretty  printing  is  initiated,  an  intermediate  pretty  printing  stream  is  wrapped  around  die  original 
output  stream  and  then  used  as  the  destination  of  output.  A  beneficial  effect  of  this  approach  is  that  it  allows 
the  user  to  use  any  kind  of  function  to  send  output  to  the  intermediate  stream  (e.g.,  in  a  print-self  function). 
All  such  output  is  captured  and  prtx:essed.  Output  is  only  sent  to  the  original  stream  after  dynamic  pretty 
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punting  decisions  have  been  made. 

The  intermediate  stream  has  to  buffer  up  output  in  order  to  make  dynamic  pretty  printing  decisions.  The 
fundamental  source  of  the  efficiency  of  the  pretty  printing  algorithm  is  that  things  are  carefully  designed  so 
that  the  int  .'mediate  stream  never  has  to  buffer  up  more  than  one  line  width  worth  of  output.  Tne  algorithm 
sends  output  to  the  underlying  stream  a  line  width  worth  at  a  time.  The  buffer  is  not  guaranteed  to  be 
completely  empty  until  die  outermost  logical  block  ends.  Thus  there  is  typically  a  delay  between  the  time 
characters  are  sent  to  the  intermediate  stream  and  the  time  they  appear  on  the  underlying  stream.  This  can  be 
confusing  if  a  process  which  is  performing  pretty  printing  is  interrupted  (c.g„  during  debugging). 

Dynamic  pretty  printing  decisions  require  a  number  of  different  calculations  involving  character  positions 
and  lengths  of  sections  of  text.  All  of  these  calculations  are  made  while  the  output  is  buffered  up  in  the 
intermediate  stream.  As  a  fundamental  simplification,  it  is  assumed  that  every  character  will  use  exaedy  one 
character  p  osition  when  actually  output  to  the  underlying  stream.  Only  newlines  are  treated  specially.  This 
assumption  can  lead  to  problems  in  some  situations.  For  example,  it  is  inadvisable  to  use  literal  tab  characters 
when  pretiy  printing.  It  should  be  noted  that  (except  for  ~T)  the  standard  FORMAT  directives  all  make  the 
same  simp  ifving  assumption. 

Intermediate  streams  work  by  intercepting  all  of  the  basic  output  messages  (i.e.,  :TY0,  : STRING-OUT, 

:  LINE-OU  \  and  :  FRESH-LINE)  being  sent  by  output  functions.  In  addition,  they  accept  some  special  new 
messages  which  support  logical  blocks  and  conditional  newlines. 

In  order  to  support  all  of  the  other  messages  (e.g.,  :READ-CURS0RP0S)  which  may  be  supported  by  the 
underlying  stream,  an  intermediate  stream  forwards  any  requests  involving  them  directly  to  the  underlying 
stream.  One  problem  with  this  is  that  since  some  of  these  messages  might  perform  output,  the  intermediate 
stream  must  empty  out  its  buffer  before  forwarding  a  request.  In  order  to  do  this,  the  intermediate  stream 
must  make  decisions  about  any  conditional  newlines.  When  it  does  this,  it  pessimistically  inserts  newlines 
everywhere  they  cannot  be  immediately  ruled  out.  As  a  result,  the  act  of  sending  an  intermediate  stream  a 
message  (such  as  :READ-CURS0RP0S)  which  it  must  send  to  the  underlying  stream  can  force  the  insertion  of 
newlines  which  would  not  otherwise  be  inserted. 

The  user  should  avoid  sending  complex  messages  to  an  intermediate  stream  (e.g.,  in  a  print-self  function). 
For  example,  an  important  reason  why  the  behavior  of  the  FORMAT  directive  -*T  was  altered  in  a  logical  block 
was  so  that  it  would  no  longer  send  :REA0-CURS0RP0S  and  :SET-CURSORPOSmessages  to  the  output  stream. 

Several  aspects  of  the  PP  system  (e.g.,  the  abbreviation  mechanisms)  depend  on  knowing  which  logical 
block  in  the  output  is  outermost.  In  order  to  determine  tins  the  following  assumptions  are  made.  Suppose 
that  printi  lg  is  in  progress  to  stream  A.  If  during  this  printing,  printing  is  initiated  on  another  stream  (B), 
then  it  is  assumed  that  die  first  block  to  occur  during  output  to  B  is  outermost.  Further,  suppose  that  during 
die  output  to  B.  output  is  again  initiated  to  stream  A.  It  is  assumed  that  this  is  separate  output  to  A,  and  that 
the  first  logical  block  to  occur  during  diis  output  to  A  will  again  be  an  outermost  block. 

The  above  assumptions  arc  not  necessarily  valid.  The  user  could  be  intending  the  output  to  streams  A  and 
B  to  operate  as  coroutines.  In  order  for  such  coroutining  output  to  work  correctly  in  conjunction  with  the  PP 
system,  th:  two  printing  coroutines  have  to  be  in  separate  processes.  It  should  be  noted  that  the  standard 
output  fui  ctions  implicitly  make  the  same  assumptions  due  to  the  way  special  variables  arc  used  to  control 
many  aspects  of  die  printing  process.  However,  the  standard  output  functions  do  not  rely  on  the  assumptions 
so  heavily. 
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Summary  of  Functions 

PPRINT  object  &opt1onal  stream 

This  is  the  same  as  the  function  PRINT  except  that  it  binds  *PRINT-PRETTY*  to  T,  does  not  print  a  trailing 
space,  and  returns  no  values. 

WRITE  object  &ksy  :stream  :escape  :base  ipretty  : level  :  1  eng th  :  1 1  nes  :array 
:rad1x  :c1rc1s  :case  :gansym 

This  outputs  object  while  allowing  (but  not  requiring)  the  specification  of  output  control  values. 

PP: INTERACTIVE-WRITE  object  Soptlonal  stream 

This  function  prints  object  on  stream  under  the  control  of  the  values  set  by 
PP: SET- INTERACTIVE -CONTROL- VARIABLES. 

PP: SET- INTERACTIVE -CONTROL-VARIABLES  &key  :escape  :ba$e  rpretty  :level  :length  :11nes 

:array  :radix  :c1rc1e  :case  :gensym 

This  function  specifies  the  output  control  values  to  be  used  by  PP:  INTERACTIVE-WRITE. 

PP:PP  &optional  object  stream 

This  prints  object  (which  defaults  to  the  last  object  abbreviated  due  to  PP: *PRINT-LINES*  by 
PP:  INTERACTIVE -write)  without  abbreviation. 

<FUNCTI0N>  <RESUME> 

Typing  <FUNCTI0N>  <RESUME>  evaluates  (PP:PP). 

PP: FAST-FORMAT  destination  control- string  &rest  args 

This  macro  is  the  same  as  the  function  FORMAT  except  that  it  is  much  more  efficient  and  destination  is 
required  to  either  be  a  literal  NIL  or  a  literal  T  or  a  stream. 

PP:  OE  FINE -LIST- PR  I  NT- FUNCTION  symbol  [list  stream)  fcbody  forms 
'['his  macro  defines  a  list  print-self  function  for  lists  whose  CAR  is  symbol. 

PP : UNDE FINE -LIST -PRINT- FUNCTION  symbol 

This  function  causes  there  to  be  no  list  print-self  function  associated  with  symbol. 

PP :  DEFINE -GENERALI  ZED- PRINT -FUNCTION  name  (object  stream)  predicate  &body  forms 

This  macro  defines  a  generalized  print-self  function  named  name.  The  predicate  is  used  to  determine 
whether  the  generalized  print-self  function  is  applicable  to  a  given  object. 

PP: GENERALIZED- PRINT- FUNCTION- ENABLED-P  name 

Determines  whether  the  named  generalized  print-self  function  is  enabled.  SETF  can  be  used  to  enable  or 
disable  a  given  generalized  print-self  function. 

PP: WITH-GENERALIZED- PRINT- FUNCTION  name  &body  forms 

This  macro  evaluates  the  forms  with  the  specified  generalized  print-self  function  enabled. 

PP:  DEFINE -FORMAT -DIRECTIVE  name  (arg  stream  colon  atsign  &r8st  parameters)  &body  forms 

This  macro  defines  a  FORMAT  directive  which  prints  a  FORMAT  argument.  The  directive  can  be  used  by 
putting  ~\packagc:namc\  in  a  FORMAT  control  string. 
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Summary  of  Variables 

•PRINT-PtETTY*  (default  NIL) 

When  non-NlL  this  standard  Common  I.isp  variable  enables  pretty  printing. 

•PRINT-ESCAPE*  (defaultT) 

When  non-NlL  this  standard  Common  I.isp  variable  forces  the  printing  of  escape  characters. 

PRINLEVEL  (default  NIL) 

When  non-NlL,  this  standard  Lisp  variable  limits  the  maximum  nesting  of  logical  blocks.  (When 
Common  Lisp  compatibility  is  introduced  this  variable  will  be  renamed  *PRINT-LEVEL*.) 

PRINLENGTH  (default  NIL) 

When  non-NlL,  this  standard  Lisp  variable  limits  the  maximum  number  of  sections  printed  in  a  logical 
block.  (When  Common  Lisp  compatibility  is  introduced  this  variable  will  be  renamed 

*prim-le:.sth*.) 

PP: 'PRINT-LINES*  (default  NIL) 

When  non-NlL,  this  variable  limits  the  number  of  lines  printed  by  an  outermost  logical  block. 

PP:*PRINT-RIGHT-MARGIN*  (default  NIL) 

When  non-NlL,  this  specifics  the  line  width  to  use  for  pretty  printing. 

PP : ‘PRINT -MISER- WIDTH*  (default  40) 

This  specifies  when  logical  blocks  should  be  printed  in  miser  mode. 
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Summary  of  Directives 

The  directive  ~W  (write  object)  uses  the  function  WRITE  to  output  the  corresponding  FORMAT  argument 
without  forcing  the  setting  of  any  output  control  variables.  The  directive  ~W  takes  the  same  parameters  as  ~A 
--  i.e.,  -mincol ,  colinc ,  minpad,  padchaM. 

-V  Prints  an  argument  following  all  output  control  variables. 

~:W  Forces  pretty  printing  and  suppresses  abbreviation. 

~0W  Forces  any  padding  to  be  inserted  on  the  left. 

There  are  three  special  directives  for  printing  lists.  Each  of  them  prints  parentheses  around  the  output  if 
and  only  if  they  are  given  an  initial  parameter  of  1. 

~\F  ILL\  Prints  as  many  elements  as  possible  on  each  line. 

~\LINEAR\  Prints  the  elements  all  on  one  line  or  one  to  a  line. 

~,c\TABULAR\  Prints  the  elements  in  a  table  with  column  spacing  c. 

The  directive  ~  1  prefix~ ;  body- ;  suffix - .  (logical  block)  iterates  over  a  list  argument  using  body  to  print  the 
elements  of  the  list  in  a  logical  block.  The  prefix  and  suffix  are  printed  before  and  after  the  body  respectively. 

~  I . . .  ~ .  Creates  a  logical  block  and  descends  into  a  list  argument 
~0 1 , . .  ~ .  Operates  on  all  the  remaining  arguments. 

~ :  I . . .  ~ .  Forces  pretty  printing  and  suppresses  abbreviation. 

-1 1  body-.  Prefix  and  suffix  default  to  "("  and  ")"  respectively. 

- 1  prefix-9 ;  ~ .  Prefix  printed  on  each  line. 

~  I  body- 9 .  Body  ,  >  anted  to  fill  the  line  width. 

The  indentation  in  a  logical  block  is  initially  set  to  the  column  position  of  the  first  character  after  the 
prefix.  The  directive  ~I  (set  indentation)  is  used  to  control  the  indentation  within  a  logical  block.  If  omitted, 
the  parameter  defaults  to  zero.  When  a  logical  block  is  printed  in  miser  mode,  all  instances  of  ~I  are  ignored. 

~/iI  Indentation  set  to  the  position  of  the  first  character  after  the  prefix  plus  n. 

-n:  I  Indentation  set  to  the  position  of  the  directive  plus  n. 

The  directive  (conditional  newline)  specifies  a  place  where  a  newline  can  be  inserted  in  a  logical  block. 
If  a  logical  block  is  being  printed  in  miser  mode  than  a  newline  is  inserted  at  every  directive  in  it.  Outside 
of  a  logical  block,  has  no  effect 

Newline  if  the  enclosing  block  is  printed  in  multi-line  mode. 

Newline  if  the  following  block  section  will  not  fit  on  the  end  of  the  line. 

~9_  Newline  only  if  the  enclosing  block  is  printed  in  miser  mode. 

When  pretty  printing  inside  of  a  logical  block,  the  directives  and  cause  indentation  (and  the 
insertion  of  any  pcr-line  prefixes)  in  the  same  way  as 

Inside  of  a  logical  block,  the  standard  FORMAT  directive  ~T  is  changed  so  that  it  tabs  relative  to  the 
beginning  of  the  containing  logical  block  section  instead  of  relative  to  the  start  of  the  line. 

Inside  of  a  logical  block,  the  standard  FORMAT  directive  ~A  is  changed  so  that  it  checks  for  the  argument 
list  being  reduced  to  a  non-NIL  atom. 
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